واجهة API التحويلات لأحداث التطبيق
تمكن واجهة API التحويلات المعلنين من إرسال أحداث الويب والتطبيق والمتجر الفعلي ومراسلات الأعمال إلى Meta من خلال نقطة نهاية واحدة بدلاً من مصادر متعددة. سيؤدي هذا الدمج إلى تبسيط مجموعة التقنيات لدى المعلن وإنشاء عرض أكثر شمولاً داخل مدير الأحداث من Meta باستخدام مجموعات البيانات.
توفر هذه الوثائق إرشادات لدمج أحداث التطبيق في واجهة API التحويلات.
المتطلبات الأساسية
1. مجموعة البيانات
يجب أن تكون أحداث التطبيق المرسلة عبر واجهة API التحويلات مرتبطة بمجموعة بيانات.
Datasets allow advertisers to connect and manage event data from web, app, store and business messaging event sources to the Conversions API. Datasets may show event data from any of these integrations that you choose to set up:
- Meta Pixel (website events)
- App Events API (app events, including Facebook SDK for iOS or Android, mobile measurement partners (MMPs))
- Offline Conversions API (Meta’s legacy API for offline events)
- Messaging Events API (messaging events)
Datasets enable you to view all customer activities from a single interface. They also allow you to reduce the effort to build and maintain multiple API integrations.
In Events Manager, advertisers have different options to create a dataset depending on their starting point. Or you can create a brand new dataset in Events Manager by linking during offline event set creation or through an existing mobile app or during messaging event set creation information. Note that linking a dataset to an application is required before sending mobile app events to the Conversions API and only one application can be linked to a dataset. See more details and instructions here.
يمكنك إرسال استدعاء GET إلى https://graph.facebook.com/v16.0/{ads-pixel-id}/is_consolidated_container لاكتشاف ما إذا كانت مجموعة بيانات المعلن مدمجة وبالتالي مؤهلة لإرسال أحداث التطبيق عبر واجهة API التحويلات.
2. الأذونات
التكوين
إرسال أحداث التطبيق إلى واجهة API التحويلات
أ. ربط معرف مجموعة البيانات ومعرف التطبيق
في مدير الأحداث، هناك طريقتان لربط تطبيقك بمجموعة بيانات:
- حدّد علامة تبويب "مصادر البيانات"، وابحث عن علامة تبويب "الإعدادات" في تطبيقك وقم بإجراء الربط.
- حدّد علامة تبويب "مصادر البيانات"، وفي علامة تبويب "نظرة عامة" في تطبيقك، استخدم زر "ربط بمجموعة البيانات" في قسم "كل الأنشطة".
بمجرد إكمال الربط، ستتضمن مجموعة البيانات التطبيق المرتبط.
ب. الحقول المطلوبة
يمكنك الرجوع هنا لمعرفة المجموعة الحالية من المعلمات التي يمكن إرسالها عبر واجهة API التحويلات. لإرسال أحداث التطبيق، يمكن مشاركة حقول server_event التالية في حمولة البيانات:
- يجب أن تحتوي المعلمة
action_sourceعلى القيمةappلأحداث التطبيق. event_idمطلوب لحالة إعداد إلغاء التكرار.
حقول بيانات التطبيق
| Parameter | Description |
|---|---|
advertiser_tracking_enabledboolean | Required for app events Use this field to specify ATT permission on an iOS 14.5+ device. Set to |
application_tracking_enabledboolean | Required for app events A person can choose to enable ad tracking on an app level. Your SDK should allow an app developer to put an opt-out setting into their app. Use this field to specify the person's choice. Use |
extinfoobject Please use the down arrow to the right to see the list of | Required for app events Extended device information, such as screen width and height. This parameter is an array and values are separated by commas. When using Note:
|
campaign_idsstring | Optional An encrypted string and non-user metadata appended to the outbound URL (for example, ad_destination_url) or deep link (for App Aggregated Event Manager) when a user clicked on a link from Facebook. Graph API definition: Parameter passed via the deep link for Mobile App Engagement campaigns. |
install_referrerstring | Optional |
installer_packagestring | Optional Used internally by the Android SDKs |
url_schemesarray | Optional Used internally by the iOS and Android SDKs. |
windows_attribution_idstring | Optional Attribution token used for Windows 10. |
معلمات معلومات العميل
| المعلمة | الوصف |
|---|---|
anon_idstring (سلسلة) | بلا تجزئة. |
madidstring (سلسلة) | بلا تجزئة. |
البيانات المخصصة
| المعلمة | الوصف |
|---|---|
descriptionstring (سلسلة) | اختياري. |
levelstring (سلسلة) | اختياري. |
max_rating_value | اختياري. |
successboolean (قيمة منطقية) | اختياري. |
باختصار، ستتطلب أحداث التطبيق التي تمت مشاركتها باستخدام واجهة API التحويلات معلمات البيانات التالية:
action_source: يجب تعيينها على ‘app’. (بمجرد استخدام واجهة API التحويلات، فإنك توافق على أن المعلمةaction_sourceدقيقة حسب معلوماتك.)event_id: مطلوب لإعداد إلغاء التكرار، انظر التفاصيل في قسم "إعداد إلغاء التكرار لعدة قنوات".
فيما يلي مثال على extinfo. تأكد من ملء جميع المعلمات الفرعية أدناه وبترتيب تسلسلي. إذا كانت هناك أي قيمة مفقودة، فيمكنك إدخال سلسلة فارغة كعنصر نائب.
| اسم المعلمة الفرعية | مطلوب | نوع البيانات | مثال |
|---|---|---|---|
extinfo version | نعم | string (سلسلة) |
|
app package name | لا | string (سلسلة) |
|
short version | لا | string (سلسلة) |
|
long version | لا | string (سلسلة) |
|
os version | نعم | string (سلسلة) |
|
device model name | لا | string (سلسلة) |
|
locale | لا | string (سلسلة) |
|
timezone abbr | لا | string (سلسلة) |
|
carrier | لا | string (سلسلة) |
|
screen width | لا | string (سلسلة) |
|
screen height | لا | string (سلسلة) |
|
screen density | لا | string (سلسلة) |
|
cpu core | لا | string (سلسلة) |
|
external storage size | لا | string (سلسلة) |
|
free space in external storage size | لا | string (سلسلة) |
|
device time zone | لا | string (سلسلة) |
|
ج. إعداد إلغاء التكرار لعدة قنوات
ستكون آلية إلغاء التكرار مطلوبة لإزالة زيارات الأحداث المكررة بين دمج واجهة API التحويلات وجميع عمليات الدمج الأخرى الموجودة لديك مع أحداث التطبيق بما في ذلك مجموعة SDK وتطبيقات MMP وواجهة API أحداث التطبيق.
بالنسبة إلى أحداث التطبيق، نقوم بتطبيق وظيفة إلغاء التكرار ذاتها الموجودة لأحداث الويب. يستفيد المنطق من إلغاء البيانات المكررة بناءً على الحقل event_id وevent_name (واجهة API التحويلات ومجموعة SDK / أحداث التطبيق التي تحمل event_id نفسه). المعلمة events_id هي معرف يمكنه التمييز بشكل فريد بين الأحداث المتشابهة. قد تؤدي معرفات الأحداث غير الدقيقة إلغاء تكرار التحويل بشكل خاطئ، مما يؤثر بشكل زائد على الإبلاغ عن التحويل وأداء الحملة الإعلانية.
يمكنك الرجوع إلى وثائق المطوّر التالية لتنفيذ إعداد إلغاء التكرار:
فيما يلي مثال على كيفية تسجيل حدث مخصص. للقيام بذلك، أدخل اسم الحدث كـ AppEvents.Name في مجموعة SDK لنظام iOS:
AppEvents.shared.logEvent(.achievedLevel, parameters: [AppEvents.ParameterName(rawValue: "event_id"): "123"])
بالنسبة لأحداث تثبيت التطبيق، توجد بالفعل آلية إلغاء تكرار تضمن إسناد عملية تثبيت واحدة فقط خلال آخر 90 يومًا. نحتفظ بالحدث الأول ونتجاهل الأحداث اللاحقة بغض النظر عن مصدر الإجراء الذي تنتمي إليه. لا توجد حاجة لتنفيذ إلغاء التكرار لأحداث التطبيق المتعلقة بأحداث التثبيت.
د. إرسال الأحداث
لإرسال أحداث جديدة، أرسل طلب POST إلى واجهة API التحويلات من هذا المسار: https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}. عند النشر على عنصر الربط هذا، تقوم Meta بإنشاء أحداث خادم تطبيق جديدة. لمزيد من التفاصيل، يرجى الرجوع إلى مستند المطوّر التالي.
فيما يلي نظرة عامة على كيفية توافق المعلمات مع المخطط العام في حمولة البيانات:
** اكتشاف الأخطاء وإصلاحها**
يمكنك استخدام أداة مساعدة حمولة البيانات لإنشاء بيانات الحمولة:
- اختر مصدر الإجراء
appإذا كان ذلك ممكنًا - املأ معلومات الأحداث التي سيتم إرسالها إلى Meta
- سيؤدي هذا إلى إنشاء حمولة بيانات الأحداث، والتي يمكن استخدامها كقالب لدمج واجهة API التحويلات
استخدم أداة اختبار الأحداث في مدير الأحداث للاختبار.