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

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

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

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

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

استخدم هذا التكامل من أجل:

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

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

قبل توصيل إعلانات Meta، تأكد من:

• أن لديك دور Admin في حساب Pushwoosh الخاص بك. راجع إدارة وصول المستخدمين والأذونات لمعرفة كيفية عمل الأدوار والأذونات.
• أن لديك Facebook Business Manager مُعدًا لإدارة أصول علامتك التجارية على Facebook، بما في ذلك حسابات الإعلانات والصفحات والتطبيقات.
• أن لديك حساب إعلانات Facebook نشطًا مرتبطًا بـ Business Manager الخاص بك.
• أن مسؤول Facebook Business Manager الخاص بك قد منحك إما أذونات Manage Campaigns أو Manage ad accounts لحسابات الإعلانات التي تخطط لاستخدامها مع Pushwoosh.
• أنك قد قبلت شروط وأحكام حساب الإعلانات لتلك الحسابات.
• أنك قد قبلت شروط الجماهير المخصصة لـ Facebook لحسابات إعلانات Facebook التي تخطط لاستخدامها مع Pushwoosh.

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

1. في Pushwoosh، انتقل إلى Settings > 3rd party integrations.

2. في بطاقة إعلانات Meta، انقر على Login page.

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

4. حدد حسابات الإعلانات التي تريد توصيلها.

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

6. انقر على Save. يعرض Meta بعد ذلك تأكيدًا بأن حسابك متصل.

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

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

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

• Ad account name
• Business account
• ID

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

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

في صفحة Meta Ads، انقر على 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 Ads، انقر على Map user data.

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

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

يربط Pushwoosh هذه الحقول تلقائيًا. لا تقوم بتعيينها في Map project tags to Meta fields:

• 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. تحت How to sync users info to the ad audience، اختر خيارًا واحدًا:

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

5. في AD PLATFORM، اختر Meta Ads. للمزامنة مع جمهور إعلانات Google بدلاً من ذلك، راجع تكامل إعلانات Google.

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

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

8. انقر على Apply لحفظ النقطة أو Cancel للإغلاق دون حفظ.

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

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

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

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

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

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

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