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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• اسم الحساب الإعلاني
• حساب الأعمال
• المعرف (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 تحدد من يدخل هذه الرحلة. على سبيل المثال، شريحة Users with tag webinar_registered set to true. هؤلاء المستخدمون فقط هم من سينتقلون عبر الرحلة ويصلون إلى Audience sync.

3. أضف نقطة Audience sync.

4. تحت How to sync users info to Meta audience، اختر خيارًا واحدًا:

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

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

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 في إحصائيات رحلة العميل.