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

مساعدة المطور مطلوبة

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

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

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

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

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

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

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

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

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

1. في Pushwoosh، انتقل إلى الإعدادات > تكاملات الطرف الثالث.

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

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

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

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

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

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

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

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

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

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

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

في صفحة إعلانات Meta، انقر على إدارة الحسابات لفتح مربع الحوار. استخدم مفتاح التبديل في كل صف لتضمين أو استبعاد ذلك الحساب الإعلاني من التكامل. انقر على تطبيق لحفظ التغييرات أو إلغاء للإغلاق دون حفظ.

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

• قم بتشغيل أو إيقاف عرض المتصل فقط لتحديد الصفوف التي تظهر.
• اكتب في البحث بالاسم أو المعرف… للعثور على الحسابات في القائمة.

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

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

ملاحظة

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

1. في صفحة إعلانات Meta، انقر على ربط بيانات المستخدم.

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

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

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

• البريد الإلكتروني
• رقم الهاتف
• MADID

3. انقر على حفظ لتطبيق الربط أو إلغاء للإغلاق دون حفظ.

تمكين جمع 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>نحن نستخدم معرف الإعلان الخاص بك لعرض إعلانات ذات صلة لك.</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 للمزامنة.

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

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

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

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

1. افتح Journey Builder.

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

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

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

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

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

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

7. انقر على تطبيق لحفظ النقطة أو إلغاء للإغلاق دون حفظ.

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

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

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

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

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

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

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