واجهة API أحداث التطبيق

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

للحصول على معلومات حول تتبع أحداث التطبيق لمراسلة النشاط التجاري، يُرجى الاطّلاع على واجهة API أحداث التطبيق لمراسلة النشاط التجاري في وثائق منصة Messenger.

طريقة العمل

توجد ثلاثة أنواع من أحداث التطبيق:

• الأحداث التي يتم تسجيلها تلقائيًا - تسجّل مجموعة Facebook SDK تلقائيًا عمليات تثبيت التطبيقات وجلسات التطبيقات وعمليات الشراء داخل التطبيق.
• الأحداث القياسية - أحداث رائجة يقوم فيسبوك بإنشائها نيابة عنك.
• الأحداث المخصصة - أحداث تقوم بإنشائها وتكون خاصة بتطبيقك.

يتكوّن حدث التطبيق من ثلاثة أجزاء:

1. name - يمثل سلسلة مطلوبة توضح الحدث. يظهر الاسم في سجل الأحداث عند إرسال حدث التطبيق إلى Analytics.
2. valueToSum - يمثل قيمة اختيارية يضيفها Analytics إلى قيم أخرى مطلوب تجميعها من أحداث التطبيق التي تحمل الاسم نفسه.
3. parameters - يمثل القيم الاختيارية المُضمنة في حدث التطبيق لديك.

أقصى عدد لأسماء الأحداث المختلفة هو 1000. ملاحظة: لن يتم تسجيل أنواع الأحداث الجديدة بمجرد الوصول إلى هذا الحد، وإذا تجاوزت هذا الحد، فقد يظهر لك الخطأ 100 Invalid parameter عند التسجيل. ومع ذلك، يمكنك تعطيل الأحداث القديمة. يمكنك الاطلاع على المزيد حول تقييدات الأحداث في الأسئلة المتكررة.

قبل البدء

ستحتاج إلى ما يلي:

• معرف المعلن أو معرف الإعلان من جهاز Android أو معرف الإعلان (IDFA) من جهاز Apple
• رمز وصول التطبيق لمصادقة فيسبوك. ولا تحاول تخزين رمز وصول التطبيق في العميل.

عمليات تثبيت التطبيق

أرسل طلب POST من الخادم إلى نقطة النهاية /{app-id}/activities مع تضمين المعلمتين application_tracking_enabled وadvertiser_tracking_enabled:

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=MOBILE_APP_INSTALL
   &application_tracking_enabled=0      
   &advertiser_tracking_enabled=0       
   &advertiser_id={advertiser-tracking-id}
   &{app-access-token}"

عند نجاح العملية، يتلقى تطبيقك الاستجابة التالية:

{
  "success": true
}

التنبيهات

• يجب الإبلاغ عن عملية تثبيت واحدة فقط لكل مستخدم. يمكنك تكرار المعرفات على مستوى المعرف والمستخدم إذا أمكن.

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

تمكين تتبع الإعلان

يحدد الحقل advertiser_tracking_enabled ما إذا كان الشخص قد قام بتمكين تتبع الإعلانات على جهازه أم لا. ويمكنك التعيين على القيمة 0 للتعطيل أو القيمة 1 للتمكين. يجب استدعاء هذه البيانات وإرجاعها إلى فيسبوك لتحديد ما إذا كان يمكن استخدام تتبع الإعلانات للتحسين أو التحويلات. ستستخدم Meta بيانات الحدث (من جانب الشركاء حول أنشطة المستخدم خارج Meta) وفقًا لسياسة البيانات لديها، بما في ذلك الإبلاغ عن الإعلانات واكتشاف الاحتيال وإنشاء منتجاتنا وتحسينها (بما في ذلك منتجات عرض الإعلانات)، ولكن ستقيد استخدام البيانات المتعلقة بذلك الشخص لإضفاء طابع شخصي على إعلانات المستخدم. بالنسبة للأجهزة التي تعمل بإصدارات أقدم من iOS 6، ينبغي تعيين هذه المعلمة افتراضيًا إلى القيمة 1.

تفضل بزيارة Apple، مرجع AdSuppport للوصول إلى حالة تتبع المستخدم.

يوضح جزء الرمز البرمجي التالي كيفية الحصول على قيمة علامة تمكين التتبع.

يمكنك الحصول على الإعداد الحالي لعلامة تمكين التتبع من الخاصية Settings.shared.isAdvertiserTrackingEnabled.

print("isAdvertiserTrackingEnabled: \(Settings.shared.isAdvertiserTrackingEnabled)")

تعطيل تتبع الإعلان

يمكن لأي تطبيق اختيار تضمين إعداد للمستخدمين يمكّنهم من إيقاف تشغيل تتبع الإعلان ضمن هذا التطبيق. ويطلب فيسبوك من شركائه تضمين هذا الخيار في مجموعة SDK التي يستخدمونها وإبلاغ فيسبوك باختيار المستخدم وحدث التثبيت أو التحويل. يستخدم فيسبوك حدث التثبيت أو التحويل في تقارير الإعلانات، إلا أنه يقيده من استخدامه في تحسين الإعلانات. يجب أن يكون إعداد المستخدم ثابتًا عبر جميع عمليات بدء تشغيل التطبيق.

أحداث التحويلات

أرسل طلب POST إلى نقطة النهاية /{app-id}/activities مع تعيين event إلى CUSTOM_APP_EVENTS وتعيين advertiser_tracking_enabled في كل حدث فردي. ويلزم توفير المعلمة advertiser_id أو attribution.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS" 
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
       "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &{app-access-token}" 

عند نجاح العملية، يتلقى تطبيقك الاستجابة التالية:

{
  "success": true
}

الإسناد

تعمل نقطة النهاية attribution على إرجاع عمليات التثبيت والتحويلات استنادًا إلى النقرات التي تم إجراؤها على أي إعلان في غضون 28 يومًا. يستخدم مدير الإعلانات المشاهدة لمدة يوم واحد من خلال نموذج الإسناد من خلال النقر لمدة 28 يومًا، وتظهر الرؤى استنادًا إلى وقت مرة ظهور الإعلان أو وقت النقر، وليس إلى وقت التثبيت أو التحويل. ويُعد ذلك مهمًا عند مقارنة تقاريرك مع تقارير مدير الإعلانات في فيسبوك. بالإضافة إلى مطالبات أحداث التطبيق القياسية للنقر على الإعلان، يجب عليك أيضًا وضع السيناريوهات التالية في الاعتبار:

• مطالبات الإسناد من خلال المشاهدة - يؤدي تعيين consider_views=TRUE إلى إرجاع بيانات الإسناد الخاصة بعمليات التثبيت التي حدثت في غضون يوم واحد من مرة ظهور الإعلان، بشرط أن حساب مركز الحسابات لم ينقر على إعلان خلال 28 يومًا. وستكون الاستجابة التي يتم إرجاعها بالقيمة is_view_through=TRUE وستحل القيمة view_time محل click_time. تتشابه كل عمليات الإسناد الأخرى كما هو الحال مع بيانات إسناد النقر على الإعلان.

• المطالبات عبر الحملات الإعلانية - يمكن للمُعلنين تتبع أداء كل الإعلانات التي أدت إلى ظهور حدث تطبيق. ويرسل فيسبوك مطالبات الأحداث من الحملات الإعلانية طالما أنه لم يتم تعيين هدف الحملة الإعلانية إلى عملية تثبيت تطبيق الهواتف المحمولة أو التفاعل مع تطبيق الهواتف المحمولة. لا تُعرض هذه البيانات إلا إذا أضاف المعلن التطبيق إلى الحقل "تتبع أحداث التطبيق بالهاتف المحمول" في إعلانه.

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

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

• حالة الاستخدام — ينقر أي مستخدم على إعلان على هاتف iPhone يعلن عن تطبيق، ثم يثبّت التطبيق نفسه على جهاز iPad. ويمكننا في هذه الحالة إسناد عملية تثبيت التطبيق التي تمت باستخدام جهاز iPad إلى الإعلان الذي ظهر على هاتف iPhone بغض النظر عن استهداف الإعلان.

المطابقة المتقدمة

تتيح لك المطابقة المتقدمة إرسال بيانات العميل إلى فيسبوك حيث نستخدم هذه البيانات لتحديد حسابات مركز الحسابات الذين يتخذون إجراءً استجابةً لإعلانك تحديدًا أكثر دقة. وعند استخدام هذه البيانات، يتمكّن فيسبوك من مطابقة أحداث التحويل مع العملاء لتحسين إعلاناتك وإنشاء جماهير أكبر لإعادة التسويق.

أرسل طلب POST إلى نقطة النهاية /{app-id}/activities مع تعيين المعلمة ud إلى معلمة ستساعدك على تتبع العميل، مثل البريد الإلكتروني للعميل أو رقم هاتفه. يجب تجزئة جميع بيانات العملاء وإلا فسيتجاهلها فيسبوك. وتأكد من تعيين advertiser_tracking_enabled في كل حدث فردي.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
      "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &ud[em]={sha256-hashed-email}
   &{app-access-token}"

عند نجاح العملية، يتلقى تطبيقك الاستجابة التالية:

{
  "success": true
}

يتعين أن تكون جميع بيانات المستخدم مُجزأة باستخدام SHA256 قبل إرسالها إلى فيسبوك. علمًا بأن فيسبوك سيتجاهل البيانات غير المُجزأة.

إلغاء التكرار

بالنسبة إلى أحداث التطبيق، نقوم بتطبيق وظيفة إلغاء التكرار ذاتها الموجودة لأحداث الويب. يستفيد المنطق من الحقل event_id وإلغاء التكرار القائم على event_name. المعلمة event_id هي المعرف الذي يمكنه التمييز بشكل فريد بين الأحداث المتماثلة. قد تؤدي معرفات الأحداث غير الدقيقة إلغاء تكرار التحويل بشكل خاطئ، مما يؤثر بشكل زائد على الإبلاغ عن التحويل وأداء الحملة الإعلانية.

معلومات الجهاز الموسّعة

أرسل معلومات الجهاز، مثل عرض الشاشة وارتفاعها، في استدعاء حدث التطبيق باستخدام /{app-id}/activities?extinfo. ويتم الفصل بين القيم بفواصل ويجب أن تكون حسب الترتيب في الفهرس الموجود في دليل مرجع /application/activites. وعند استخدام extinfo، يلزم توفير كل القيم.

• يجب أن يتوفر version بالقيمة a2 لنظام Android
• يجب أن يتوفر version بالقيمة i2 لنظام iOS

المرجع

• معلمات ApplicationActivities
• وثائق مطوّري نظام Android - أدوات قياس العرض
• وثائق مطوّري نظام Android - وحدة التخزين الخارجية
• وثائق مطوّري Apple - أدوات قياس العرض
• وثائق مطوّري Apple - مساحة التخزين الخارجية
• وثائق مطوّري Apple - حجم الشاشة

الحصول على ملفات تعريف الارتباط بالهواتف المحمولة

نشجّعك على ربط أحداث التطبيق بمعرف advertiser_id. وعلى الرغم من ذلك وبالنسبة لأجهزة Android وأجهزة iOS التي تعمل بإصدار أقدم من الإصدار iOS 6، يمكنك أيضًا استخدام المعلمة attribution التي يتم تعيينها إلى ملف تعريف الارتباط بالهاتف المحمول الخاص بالجهاز.

ملاحظة: لا يتم اشتقاق ملفات تعريف الارتباط بالهواتف المحمولة من أي تعيينات لنسبة الإسهام في التحويل ترتبط بأي مستخدم أو جهاز. ملفات تعريف الارتباط هذه ليست ثابتة ومُصممة بحيث سيتم تحديثها باستمرار. لا تستخدم ملفات تعريف الارتباط بالهواتف المحمولة لإعادة استهداف الإعلانات.

Android

ملف تعريف الارتباط هو سلسلة عشوائية تتألف من حروف وأرقام بطول 22 حرفًا.

احصل على معرف الإسناد من فيسبوك باستخدام ContentProvider:

public static final Uri ATTRIBUTION_ID_CONTENT_URI = Uri.parse("content://com.facebook.katana.provider.AttributionIdProvider");

public static final String ATTRIBUTION_ID_COLUMN_NAME = "aid";

public static String getAttributionId(ContentResolver contentResolver) {
        String [] projection = {ATTRIBUTION_ID_COLUMN_NAME};
        Cursor c = contentResolver.query(ATTRIBUTION_ID_CONTENT_URI, projection, null, null, null);
        if (c == null || !c.moveToFirst()) {
            return null;
        }
        String attributionId = c.getString(c.getColumnIndex(ATTRIBUTION_ID_COLUMN_NAME));
        c.close();
        return attributionId;
    }

كما يجب عليك الحصول على معرف الإعلان الخاص بتطبيق Android لديك.

iOS

يتم إنشاء ملف تعريف الارتباط بالهاتف المحمول من خلال تطبيقات تعمل بنظام iOS على فيسبوك باستخدام CFUUIDCreateString وهو عبارة عن تمثيل سلسلة معرفات UUID بوحدة‏ 128 بت.

احصل على معرف ملف تعريف الارتباط ومعرف IDFA، ثم أرسلهما إلى فيسبوك باعتبارهما معرفًا:

ASIdentifierManager *manager = [ASIdentifierManager sharedManager];
NSString *advertiserID = [[manager advertisingIdentifier] UUIDString];

if (advertiserID) {
  // do stuff
}

عنوان X-Forwarded-For HTTP

إذا تم إجراء طلبات POST من مكان مركزي مثل الخادم أو الوكيل وبشكل أساسي استدعاء خادم إلى خادم، فيلزم توفير عنوان X-Forwarded-For HTTP لضمان الحصول على معلومات دقيقة حول الموقع والجهاز. أرسل عنوان IP الخاص بالجهاز بتنسيق IPv4 أو IPv6 عبر معلمة عنوان X-Forwarded-For HTTP في كل طلبات أحداث التطبيق التي ترسلها. ومن خلال إجراء ذلك، فإنه يسمح لنا بإقران المعرف advertiser_id مع عنوان IP الصحيح والذي يمكننا استخدامه بعد ذلك في منصتنا.

مثال على IPv6

curl ...
  -H "X-Forwarded-For: fd45:f238:3b40:23b1:ffff:ffff:ffff:abcd" \
  https://graph.facebook.com/<APP_ID>/activities/

مثال على IPv4

curl ...
  -H "X-Forwarded-For: 192.168.0.99" \
  https://graph.facebook.com/<APP_ID>/activities

الاختبار

1. انتقِل إلى مدير الأحداث.
2. انقر على أيقونة مصادر البيانات في الجانب الأيمن من الصفحة.
3. حدد اسم ومعرف البيانات.
4. انقر على اختبار الأحداث، وحدد القناة كتطبيق.
5. أرسل طلب AE-API باستخدام أداة graph api.
6. ستظهر التفاعلات قريبًا في علامة تبويب الأحداث الاختبارية.

الاختلافات

في حالة ما إذا قام العميل بمقارنة تقارير قياس أحد شركاء قياس أداء تطبيقات الهواتف المحمولة مع تقارير فيسبوك ورأى اختلافًا بينهما، ففيما يلي بعض العناصر للتحقق منها:

إذا كان تقرير فيسبوك يعرض عمليات تثبيت أقل مما يعرضها تقرير شريك قياس أداء تطبيقات الهواتف المحمولة:

• هل تم دمج مجموعة FB SDK بشكل صحيح؟
• هل يستخدم العميل معرف التطبيق الخاطئ؟

إذا كان تقرير فيسبوك يعرض عمليات تثبيت أكثر مما يعرضها تقرير MMP:

• هل تتطابق فترات الإسناد؟ يستخدم فيسبوك عادة فترات إسناد أكبر من الغالبية العظمى من شركاء قياس أداء تطبيقات الهواتف المحمولة.
• هل تم دمج مجموعة MMP SDK بشكل صحيح؟
• هل يستخدم العميل معرف التطبيق الخاطئ؟
• هل تحدث الاختلافات في إصدار نظام التشغيل iOS7 فقط؟ هل يتلقى شريك قياس أداء تطبيقات الهواتف المحمولة (MMP) معرف إعلانات Apple‏ (IDFA) من الجهاز ويقوم بإدخاله إلى FB بشكل صحيح؟

المرجع

معلومات Extinfo لأنشطة التطبيق

لمزيد من المعلومات حول معلومات التطبيق الموسّعة، تفضل بزيارة دليل مرجع /application/activites.

معلمات بيانات المستخدمين

أسماء الأحداث القياسية

معلمات الأحداث القياسية

راجع أيضًا

• أحداث التطبيق
• أفضل ممارسات أحداث التطبيق
• معالجة الأخطاء
• الامتثال باللائحة العامة لحماية البيانات (GDPR)
• مدير الإعلانات من فيسبوك
• لوحة معلومات التطبيق من فيسبوك