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

<Aside type="caution" icon="setting" title="تحتاج إلى مساعدة المطور">
 ستحتاج إلى مساعدة من فريق التطوير لديك لإعداد التكامل. يرجى مشاركة هذا الدليل معهم.
</Aside>

يتيح لك تكامل [إعلانات Meta](https://www.facebook.com/business/ads) مزامنة جماهير Pushwoosh مع حسابات إعلانات Meta الخاصة بك. استخدمه لاستهداف أو استبعاد المستخدمين في الحملات الإعلانية وإضافة الإعلانات المدفوعة كقناة أخرى في رحلة عميلك.

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

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

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


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

* لديك دور **Admin** في حساب Pushwoosh الخاص بك. راجع [إدارة وصول المستخدمين والأذونات](/ar/product/account-management-and-security/multi-login-accounts/#creating-and-managing-roles-also-known-as-groups) لمعرفة كيفية عمل الأدوار والأذونات.
* لديك [**مدير أعمال فيسبوك (Facebook Business Manager)**](https://www.facebook.com/business/tools/business-manager) مُعد لإدارة أصول علامتك التجارية على فيسبوك، بما في ذلك حسابات الإعلانات والصفحات والتطبيقات.
* لديك [**حساب إعلاني نشط على فيسبوك (Facebook Ad Account)**](https://www.facebook.com/business/tools/ads-manager) مرتبط بمدير أعمالك.
* لقد منحك مسؤول مدير أعمال فيسبوك إما أذونات **إدارة الحملات (Manage Campaigns)** أو **إدارة حسابات الإعلانات (Manage ad accounts)** للحسابات الإعلانية التي تخطط لاستخدامها مع Pushwoosh.
* لقد قبلت شروط وأحكام الحساب الإعلاني لتلك الحسابات.
* لقد قبلت [**شروط الجماهير المخصصة لفيسبوك (Facebook's Custom Audiences Terms)**](https://business.facebook.com/legal/terms/customaudience) لحسابات إعلانات فيسبوك التي تخطط لاستخدامها مع Pushwoosh.

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

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

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

<img src="/integrations-meta-ads-integration-1.webp" alt="صفحة تكاملات الطرف الثالث مع بطاقة إعلانات Meta التي تعرض روابط التكوين ودليل الإعداد وصفحة تسجيل الدخول"/>

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

4. حدد الحسابات الإعلانية التي تريد ربطها.
<img src="/integrations-meta-ads-integration-6.webp" alt="شاشة Meta لاختيار خيار وصول الأعمال للتكامل المتصل" width="480" />

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

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

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


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

<img src="/integrations-meta-ads-integration-8.webp" alt="صفحة إعلانات Meta في Pushwoosh مع شارة متصل، وجدول حسابات الإعلانات مع عمود حساب الأعمال، وإجراءات الرأس، وكيفية مزامنة الجماهير مع Meta" />

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

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

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

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

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

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

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

<img src="/integrations-meta-ads-integration-4.webp" alt="مربع حوار إدارة حسابات الإعلانات مع زر تبديل إظهار المتصل فقط، والبحث بالاسم أو المعرف، وأزرار تبديل الصفوف مع شارات متصل أو غير متصل، وإلغاء وتطبيق" />



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

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

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

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

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

<img src="/integrations-meta-ads-integration-3.webp" alt="نافذة ربط وسوم المشروع بحقول Meta مع أعمدة حقل فيسبوك واسم الوسم، ومربع اختيار الكتابة فوق، وإلغاء وحفظ" width="480" />

<Aside type="note" title="الحقول المربوطة تلقائيًا">
يربط Pushwoosh هذه الحقول تلقائيًا. لا تقوم بتعيينها في **ربط وسوم المشروع بحقول Meta**:

* **البريد الإلكتروني (Email)**
* **رقم الهاتف (Phone number)**
* **MADID**
</Aside>
3. انقر فوق **حفظ (Save)** لتطبيق الربط أو **إلغاء (Cancel)** للإغلاق دون حفظ.

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

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

<Tabs syncKey="maid-sdk">
<TabItem label="Android">

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

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

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

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

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

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

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

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

```java

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

Pushwoosh.getInstance().setAdvertisingId(gaid);

```

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

```java
Pushwoosh.getInstance().setAdvertisingId(null);
```

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

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

</TabItem>
<TabItem label="iOS">

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

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

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

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

إذا كان تطبيقك يستخدم IDFA للتتبع، فإن Apple تطلب منك إدراج النطاقات التي تتلقى بيانات التتبع في [بيان الخصوصية](https://developer.apple.com/documentation/bundleresources/privacy-manifest-files) الخاص بك (`PrivacyInfo.xcprivacy`). راجع [TN3182](https://developer.apple.com/documentation/technotes/tn3182-adding-privacy-tracking-keys-to-your-privacy-manifest) للاطلاع على المتطلبات الكاملة.

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

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

<Aside type="note">
إذا لم يمنح المستخدم إذن ATT، فإن iOS يحظر طلبات الشبكة إلى جميع النطاقات المدرجة في `NSPrivacyTrackingDomains`. لن يتم إرسال MADID بغض النظر عما يفعله الكود الخاص بك.
</Aside>

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

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

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

```swift
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` أو سلسلة فارغة:

```swift
Pushwoosh.configure.setAdvertisingId(nil)
```

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

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

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

</TabItem>
</Tabs>

### كيف يعمل

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


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

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

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

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

1. افتح [**منشئ الرحلات (Journey Builder)**](/ar/product/customer-journey/pushwoosh-journey-overview/).

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

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

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

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

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

<img src="/integrations-meta-ads-integration-10.webp" alt="لوحة مزامنة الجمهور مع قائمة منسدلة للجمهور وجمهور Meta المخصص المحدد" />

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

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

<img src="/integrations-meta-ads-integration-9.webp" alt="لوحة مزامنة الجمهور مع اسم الخطوة، إضافة أو إزالة المستخدمين، حساب إعلانات Meta، الجمهور، تطبيق وإلغاء" />

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

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

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

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

## إحصائيات مزامنة الجمهور
بعد الإطلاق، افتح إحصائيات خطوة **مزامنة الجمهور (Audience sync)** لرؤية حجم الدخول، والإضافات والإزالات، والملفات الشخصية التي تم تخطيها. للحصول على تفاصيل المقاييس، راجع [**مزامنة الجمهور (Audience sync)**](/ar/product/statistics-and-analytics/journey-statistics/journey-element-statistics/#audience-sync) في **إحصائيات رحلة العميل (Customer Journey statistics)**.

<img src="/integrations-meta-ads-integration-11.webp" alt="إحصائيات مزامنة الجمهور مع إجمالي الإدخالات، المضاف إلى جمهور Meta، المحذوف من جمهور Meta، التخطي غير المتزامن ينتقل إلى الخطوة التالية، تصدير المستخدمين، وحساب إعلانات Meta للمزامنة" />