تكامل إعلانات Meta

تحتاج إلى مساعدة المطور

ستحتاج إلى مساعدة من فريق التطوير لديك لإعداد التكامل. يرجى مشاركة هذا الدليل معهم.

يتيح لك تكامل إعلانات Meta مزامنة جماهير Pushwoosh مع حسابات إعلانات Meta الخاصة بك. استخدمه لاستهداف أو استبعاد المستخدمين في الحملات الإعلانية وإضافة الإعلانات المدفوعة كقناة أخرى في رحلة عميلك.

حالات الاستخدام

استخدم هذا التكامل لـ:

• استهداف المستخدمين ذوي القيمة العالية في قنوات متعددة لزيادة عمليات الشراء أو التفاعل
• إعادة استهداف المستخدمين الأقل استجابة في القنوات الأخرى
• بناء جماهير قمع حتى لا يتلقى العملاء الأوفياء إعلانات غير ضرورية

المتطلبات الأساسية

قبل ربط إعلانات Meta، تأكد من:

• لديك دور Admin في حساب Pushwoosh الخاص بك. راجع إدارة وصول المستخدمين والأذونات لمعرفة كيفية عمل الأدوار والأذونات.
• لديك مدير أعمال فيسبوك (Facebook Business Manager) مُعد لإدارة أصول علامتك التجارية على فيسبوك، بما في ذلك حسابات الإعلانات والصفحات والتطبيقات.
• لديك حساب إعلاني نشط على فيسبوك (Facebook Ad Account) مرتبط بمدير أعمالك.
• لقد منحك مسؤول مدير أعمال فيسبوك إما أذونات إدارة الحملات (Manage Campaigns) أو إدارة حسابات الإعلانات (Manage ad accounts) للحسابات الإعلانية التي تخطط لاستخدامها مع Pushwoosh.
• لقد قبلت شروط وأحكام الحساب الإعلاني لتلك الحسابات.
• لقد قبلت شروط الجماهير المخصصة لفيسبوك (Facebook’s Custom Audiences Terms) لحسابات إعلانات فيسبوك التي تخطط لاستخدامها مع Pushwoosh.

إعداد إعلانات Meta في Pushwoosh

1. في Pushwoosh، انتقل إلى الإعدادات (Settings) > تكاملات الطرف الثالث (3rd party integrations).

2. في بطاقة إعلانات Meta، انقر فوق صفحة تسجيل الدخول (Login page).

3. سجل الدخول إلى حساب Meta الخاص بك، ثم انقر فوق متابعة (Continue).

4. حدد الحسابات الإعلانية التي تريد ربطها.

5. راجع الأذونات المطلوبة للوصول إلى الحساب الإعلاني والأعمال.

6. انقر فوق حفظ (Save). ثم يعرض Meta تأكيدًا على أن حسابك متصل.

مراجعة حالة الاتصال

بعد الإعداد، سيتم إعادة توجيهك إلى صفحة إعلانات Meta في Pushwoosh.

يسرد جدول حسابات الإعلانات كل حساب متصل مع:

• اسم الحساب الإعلاني
• حساب الأعمال
• المعرف (ID)

افتح النقاط الثلاث في نهاية الصف واختر إزالة الحساب الإعلاني (Remove ad account) لحذف ذلك الحساب الإعلاني من القائمة في Pushwoosh.

إدارة حسابات الإعلانات المتصلة

في صفحة إعلانات Meta، انقر فوق إدارة الحسابات (Manage accounts) لفتح مربع الحوار. استخدم زر التبديل في كل صف لتضمين أو استبعاد ذلك الحساب الإعلاني من التكامل. انقر فوق تطبيق (Apply) لحفظ التغييرات أو إلغاء (Cancel) للإغلاق دون حفظ.

لتعديل عرض القائمة:

• قم بتشغيل أو إيقاف إظهار المتصل فقط (Show only connected) لتحديد الصفوف التي تظهر.
• اكتب في البحث بالاسم أو المعرف… (Search by name or id…) للعثور على الحسابات في القائمة.

ربط وسوم المشروع بحقول Meta

يسمح لك ربط خصائص المستخدم بإخبار Pushwoosh بأي من سمات مستخدم Meta يجب أن تحدّث حقول اسم الوسم (Tag name) في مشروعك. بهذه الطريقة، عندما تأتي البيانات من Meta، يتم حفظها حيث تتوقع.

ملاحظة

لمزامنة الجمهور، يرسل Pushwoosh دائمًا معرفًا واحدًا لكل مستخدم من البريد الإلكتروني (Email)، أو رقم الهاتف (Phone number)، أو MADID، اعتمادًا على ما هو موجود في الملف الشخصي. قم بتكوين الربط عندما تريد أن يتلقى Meta سمات مستخدم إضافية بخلاف المعرفات المذكورة أعلاه.

1. في صفحة إعلانات Meta، انقر فوق ربط بيانات المستخدم (Map user data).

2. لكل حقل فيسبوك (Facebook field) في العمود الأيسر، اختر اسم وسم (Tag name) في مشروعك من عنصر التحكم على اليمين. اربط فقط الصفوف التي تحتاجها.

الحقول المربوطة تلقائيًا

يربط Pushwoosh هذه الحقول تلقائيًا. لا تقوم بتعيينها في ربط وسوم المشروع بحقول Meta:

• البريد الإلكتروني (Email)
• رقم الهاتف (Phone number)
• MADID

3. انقر فوق حفظ (Save) لتطبيق الربط أو إلغاء (Cancel) للإغلاق دون حفظ.

تمكين جمع MADID في SDK

تطابق إعلانات Meta المستخدمين باستخدام معرفات الأجهزة (MADID) التي يتم جمعها عبر SDK المحمول. لا يجمع Pushwoosh SDK معرفات الإعلانات (GAID على Android، IDFA على iOS) تلقائيًا. تتطلب كلتا المنصتين موافقة صريحة من المستخدم قبل قراءة المعرف. في تطبيقك، اطلب موافقة المستخدم، واقرأ المعرف عند السماح بذلك، ومرر القيمة إلى SDK.

Android

1. أضف التبعية

implementation 'com.google.android.gms:play-services-ads-identifier:...'

2. صرح بإذن AD_ID (مطلوب لـ targetSdk ≥ 33)

أضف هذا إلى ملف AndroidManifest.xml الخاص بك:

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

تنبيه

بدون هذا الإذن على Android 13+، تُرجع AdvertisingIdClient.getAdvertisingIdInfo() بصمت UUID صفريًا (00000000-0000-0000-0000-000000000000). يقوم Pushwoosh SDK بتطبيع ذلك إلى null، لذلك لا يتم إرسال MADID إلى الخادم ولن تعمل مطابقة جمهور Meta.

3. استرجع GAID ومرره إلى SDK

يجب استدعاء getAdvertisingIdInfo على خيط خلفي:

String gaid = AdvertisingIdClient.getAdvertisingIdInfo(context).getId();

Pushwoosh.getInstance().setAdvertisingId(gaid);

لمسح القيمة المخزنة في الواجهة الخلفية، مرر null أو سلسلة فارغة:

Pushwoosh.getInstance().setAdvertisingId(null);

ملاحظات السلوك:

• إذا لم تتغير القيمة منذ آخر استدعاء ناجح، فلن يتم إجراء أي طلب شبكة.
• إذا فشل طلب الشبكة، أعد المحاولة عند تشغيل التطبيق التالي.
• يتم تجاهل الاستدعاء عندما يكون Pushwoosh.stopCommunication() نشطًا.
• يتم التعامل مع UUID الصفري (00000000-0000-0000-0000-000000000000) بنفس طريقة null — يتم مسح MADID المخزن في الواجهة الخلفية.

iOS

1. أضف وصف الاستخدام إلى Info.plist

تتطلب Apple هذا المفتاح قبل إظهار مربع حوار إذن ATT:

<key>NSUserTrackingUsageDescription</key>
<string>We use your advertising identifier to show you relevant ads.</string>

2. صرح بنطاق التتبع في بيان الخصوصية الخاص بك

إذا كان تطبيقك يستخدم IDFA للتتبع، فإن Apple تطلب منك إدراج النطاقات التي تتلقى بيانات التتبع في بيان الخصوصية الخاص بك (PrivacyInfo.xcprivacy). راجع TN3182 للاطلاع على المتطلبات الكاملة.

قم بتعيين NSPrivacyTracking إلى true وأضف نطاق تتبع Pushwoosh إلى NSPrivacyTrackingDomains:

<key>NSPrivacyTracking</key>
<true/>
<key>NSPrivacyTrackingDomains</key>
<array>
    <string>tracking.svc-nue.pushwoosh.com</string>
</array>

ملاحظة

إذا لم يمنح المستخدم إذن ATT، فإن iOS يحظر طلبات الشبكة إلى جميع النطاقات المدرجة في NSPrivacyTrackingDomains. لن يتم إرسال MADID بغض النظر عما يفعله الكود الخاص بك.

3. اطلب إذن التتبع ومرر IDFA إلى SDK

يتطلب ATTrackingManager نظام iOS 14 أو أحدث. إذا كان هدف النشر الخاص بك أقل من iOS 14، فقم بتضمين الاستدعاء في فحص التوفر.

لا يستدعي Pushwoosh SDK ATTrackingManager. اطلب إذن التتبع في تطبيقك، ثم مرر النتيجة إلى SDK:

import AppTrackingTransparency
import AdSupport

if #available(iOS 14, *) {
    ATTrackingManager.requestTrackingAuthorization { status in
        let idfa = status == .authorized
            ? ASIdentifierManager.shared().advertisingIdentifier.uuidString
            : nil
        Pushwoosh.configure.setAdvertisingId(idfa)
    }
}

لمسح القيمة المخزنة في الواجهة الخلفية، مرر nil أو سلسلة فارغة:

Pushwoosh.configure.setAdvertisingId(nil)

ملاحظات السلوك:

• إذا لم تتغير القيمة منذ آخر استدعاء ناجح، فلن يتم إجراء أي طلب شبكة.
• إذا فشل طلب الشبكة، استدع setAdvertisingId مرة أخرى عند تشغيل التطبيق التالي.
• يتم تجاهل الاستدعاء عند تعطيل Pushwoosh_ALLOW_SERVER_COMMUNICATION.
• يتم التعامل مع UUID الصفري (00000000-0000-0000-0000-000000000000) بنفس طريقة nil أو السلسلة الفارغة — يتم مسح MADID المخزن في الواجهة الخلفية.

استدعِ requestTrackingAuthorization من تدفق واجهة المستخدم الرئيسية لتطبيقك. توصي Apple بالقيام بذلك بعد عرض شاشتك التوضيحية الخاصة، وليس فور التشغيل.

كيف يعمل

بمجرد استدعاء setAdvertisingId، يرسل SDK القيمة إلى نقطة نهاية تتبع Pushwoosh كحقل madid إلى جانب رمز التطبيق ومعرف جهاز الجهاز. يستخدم Pushwoosh هذا المعرف لمطابقة سجلات جهازك مع جماهير إعلانات Meta للمزامنة.

مزامنة الجماهير في الرحلات

تربط نقطة مزامنة الجمهور (Audience sync) في منشئ الرحلات (Journey Builder) رحلتك بجمهور مخصص في Meta. في كل مرة يصل فيها مستخدم إلى تلك النقطة، يطلب Pushwoosh من Meta إما إضافته إلى الجمهور أو إزالته منه.

على سبيل المثال، يمكنك استخدام هذا لإيقاف عرض إعلان ندوة عبر الإنترنت للمستخدمين الذين سجلوا بالفعل، حتى لا تهدر الإنفاق الإعلاني على الأشخاص الذين لم يعودوا بحاجة إلى رؤيته.

لتكوين مزامنة الجمهور:

1. افتح منشئ الرحلات (Journey Builder).

2. أضف مدخل قائم على الجمهور (Audience-based entry). في مصدر الجمهور (Audience source)، اختر شريحة أو قائمة Pushwoosh تحدد من يدخل هذه الرحلة. على سبيل المثال، شريحة المستخدمون الذين لديهم الوسم webinar_registered معين إلى true. فقط هؤلاء المستخدمون سينتقلون عبر الرحلة ويصلون إلى مزامنة الجمهور (Audience sync).

3. أضف نقطة مزامنة الجمهور (Audience sync).

4. تحت كيفية مزامنة معلومات المستخدمين مع جمهور Meta، اختر خيارًا واحدًا:

   • إضافة مستخدمين إلى الجمهور. يضيف كل مستخدم يصل إلى هذه الخطوة إلى جمهور Meta الذي تحدده. على سبيل المثال، استخدم هذا لبدء عرض إعلان للمستخدمين الذين سجلوا ولكن لم يحضروا بعد.
   • إزالة مستخدمين من الجمهور. يزيل كل مستخدم يصل إلى هذه الخطوة من جمهور Meta هذا. في هذا المثال، حدد هذا الخيار لإيقاف عرض إعلان الندوة عبر الإنترنت للمستخدمين الذين سجلوا بالفعل.

5. في حساب إعلانات Meta، حدد الحساب الإعلاني المتصل.

6. في الجمهور (Audience)، حدد جمهور Meta، على سبيل المثال Webinar.

7. انقر فوق تطبيق (Apply) لحفظ النقطة أو إلغاء (Cancel) للإغلاق دون حفظ.

8. أكمل تكوين الرحلة، ثم أطلقها.

عندما يصل هؤلاء المستخدمون إلى مزامنة الجمهور (Audience sync)، يتم إزالتهم من جمهور Webinar في Meta، لذلك لم يعودوا يرون إعلان الندوة عبر الإنترنت هناك.

السلوك ومعالجة الأخطاء

تعتمد معالجة الرحلة على توفر حساب Meta والجمهور:

• يقوم Meta بتحديث الجمهور فقط عندما يتمكن من مطابقة المستخدم من البيانات التي يوفرها Pushwoosh. إذا لم يتمكن Meta من مطابقة المستخدم، فلن يتغير الجمهور لذلك المستخدم، وسيستمرون في الرحلة.
• إذا وصل ملف شخصي إلى نقطة مزامنة الجمهور (Audience sync) بينما كان الحساب الإعلاني المتصل غير متصل، تتوقف الرحلة لذلك الملف الشخصي ويرسل Pushwoosh إشعارات النظام والبريد الإلكتروني.
• إذا لم يتم العثور على جمهور محدد في Meta وأعاد API خطأ، تتوقف الرحلة لذلك الملف الشخصي ويرسل Pushwoosh إشعارات النظام والبريد الإلكتروني.

إحصائيات مزامنة الجمهور

بعد الإطلاق، افتح إحصائيات خطوة مزامنة الجمهور (Audience sync) لرؤية حجم الدخول، والإضافات والإزالات، والملفات الشخصية التي تم تخطيها. للحصول على تفاصيل المقاييس، راجع مزامنة الجمهور (Audience sync) في إحصائيات رحلة العميل (Customer Journey statistics).