واجهة 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 مطلوب لحالة إعداد إلغاء التكرار.
حقول app_data
حقول user_data
حقول custom_data

حقول بيانات التطبيق

Parameter	Description
`advertiser_tracking_enabled` boolean	Required for app events Use this field to specify ATT permission on an iOS 14.5+ device. Set to `0` for disabled or `1` for enabled.
`application_tracking_enabled` boolean	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 `0` for disabled, `1` for enabled. `
`extinfo` object Please use the down arrow to the right to see the list of `extinfo` values.	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 `extinfo`, all values are required and must be in the order indexed below. If a value is missing, fill with an empty string as a placeholder. Note: `version` must be `a2` for Android `version` must be `i2` for iOS
`0` string	Required extinfo version Example: `i2`
`1` string	app package name Example: `com.facebook.sdk.samples.hellofacebook`
`2` string	short version (int or string) Example: `1.0`
`3` string	long version Example: `1.0 long`
`4` string	Required OS version Example: `13.4.1`
`5` string	device model name Example: `iPhone5,1`
`6` string	locale Example: `En_US`
`7` string	timezone abbreviation Example: `PDT`
`8` string	carrier Example: `AT&T`
`9` string	screen width Example: `320`
`10` string	screen height Example: `568`
`11` string	screen density Example: `2`
`12` string	CPU cores Example: `2`
`13` string	external storage size in GB Example: `13`
`14` string	free space on external storage in GB Example: `8`
`15` string	device timezone Example: `USA/New York`
`campaign_ids` string	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_referrer` string	Optional Third party install referrer, currently available for Android only, see here for more.
`installer_package` string	Optional Used internally by the Android SDKs
`url_schemes` array	Optional Used internally by the iOS and Android SDKs.
`vendor_id` string	Optional Vendor ID.
`windows_attribution_id` string	Optional Attribution token used for Windows 10.

معلمات معلومات العميل

المعلمة	الوصف
`anon_id` string (سلسلة)	بلا تجزئة. معرف التثبيت. يمثل هذا الحقل مثيلات تثبيت التطبيق الفريدة.
`madid` string (سلسلة)	بلا تجزئة. معرف المعلن على الهاتف المحمول أو معرف الإعلان من جهاز Android أو معرف الإعلان (IDFA) من جهاز Apple.

البيانات المخصصة

المعلمة	الوصف
`description` string (سلسلة)	اختياري. String (سلسلة)، وصف الحدث، مخصص.
`level` string (سلسلة)	اختياري. String (سلسلة)، مستوى اللعبة، مخصص.
`max_rating_value`	اختياري. Long (قيمة طويلة)، الحدود القصوى لمقياس التقييم، على سبيل المثال 5 على مقياس 5 نجوم، مخصص.
`success` boolean (قيمة منطقية)	اختياري. `1` من أجل نعم، `0` من أجل لا، مخصص.

باختصار، ستتطلب أحداث التطبيق التي تمت مشاركتها باستخدام واجهة API التحويلات معلمات البيانات التالية:

action_source: يجب تعيينها على ‘app’. (بمجرد استخدام واجهة API التحويلات، فإنك توافق على أن المعلمة action_source دقيقة حسب معلوماتك.)
event_id: مطلوب لإعداد إلغاء التكرار، انظر التفاصيل في قسم "إعداد إلغاء التكرار لعدة قنوات".
advertiser_tracking_enabled
application_tracking_enabled
extinfo

فيما يلي مثال على extinfo. تأكد من ملء جميع المعلمات الفرعية أدناه وبترتيب تسلسلي. إذا كانت هناك أي قيمة مفقودة، فيمكنك إدخال سلسلة فارغة كعنصر نائب.

اسم المعلمة الفرعية	مطلوب	نوع البيانات	مثال
إصدار extinfo	نعم	string (سلسلة)	`i2` (يجب أن يكون الإصدار a2 لنظام Android، وأن يكون i2 لنظام iOS)
app package name	لا	string (سلسلة)	`com.facebook.sdk.samples.hellofacebook`
short version	لا	string (سلسلة)	`1.0`
long version	لا	string (سلسلة)	`1.0 long`
os version	نعم	string (سلسلة)	`13.4.1`
device model name	لا	string (سلسلة)	`iPhone5,1`
locale	لا	string (سلسلة)	`En_US`
timezone abbr	لا	string (سلسلة)	`PDT`
carrier	لا	string (سلسلة)	`AT&T`
screen width	لا	string (سلسلة)	`320`
screen height	لا	string (سلسلة)	`568`
screen density	لا	string (سلسلة)	`2`
cpu core	لا	string (سلسلة)	`2`
external storage size	لا	string (سلسلة)	`13`
free space in external storage size	لا	string (سلسلة)	`8`
device time zone	لا	string (سلسلة)	`USA/New York`

ج. إعداد إلغاء التكرار لعدة قنوات

ستكون آلية إلغاء التكرار مطلوبة لإزالة زيارات الأحداث المكررة بين دمج واجهة 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 بإنشاء أحداث خادم تطبيق جديدة. لمزيد من التفاصيل، يرجى الرجوع إلى مستند المطوّر التالي.

فيما يلي نظرة عامة على كيفية توافق المعلمات مع المخطط العام في حمولة البيانات:

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": 1684389752,
            "action_source": "app",
            "user_data": {
                "em": [
                    "30a79640dfd8293d4f4965ec11821f640ca77979ca0a6b365f06372f81a3f602"
                ],
                "ph": [
                    "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b",
                    "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b"
                ],
                "madid": "bbbbbbbbbbbb",
      "anon_id": "cccccccc"
            },
            "custom_data": {
                "currency": "USD",
                "value": "142.52"
            },
            "app_data": {
                "advertiser_tracking_enabled": "True",
                "application_tracking_enabled": "True",
                "campaign_ids": "aaaaaaaaa",
                "extinfo": [
                    "a2",
                    "com.some.app",
                    "771",
                    "Version 7.7.1",
                    "10.1.1",
                    "OnePlus6",
                    "en_US",
                    "GMT-1",
                    "TMobile",
                    "1920",
                    "1080",
                    "2.00",
                    "2",
                    "128",
                    "8",
                    "USA/New York"
                ]
            }
        }
    ]
}

استكشاف الأخطاء وإصلاحها

يمكنك استخدام أداة مساعدة حمولة البيانات لإنشاء بيانات الحمولة:

اختر مصدر الإجراء app إذا كان ذلك ممكنًا
املأ معلومات الأحداث التي سيتم إرسالها إلى Meta
سيؤدي هذا إلى إنشاء حمولة بيانات الأحداث، والتي يمكن استخدامها كقالب لدمج واجهة API التحويلات

استخدم أداة اختبار الأحداث في مدير الأحداث للاختبار.