إحالة تثبيت Meta

يعرض هذا المستند كيفية استخدام إحالة تثبيت Meta في تطبيق Android للحصول على بيانات تعريف الحملات الإعلانية لفيسبوك وInstagram وAudience Network حيث يكون الهدف هو عمليات تثبيت التطبيق. في حين أن إحالة تثبيت Google Play Install Referrer (GPIR) لا توفر إلا معلومات حول عمليات النقر للتثبيت في الجلسة ذاتها، فإن إحالة تثبيت Meta تتضمن بيانات لما يلي:

• عمليات التثبيت من خلال العرض (VT)
• عمليات التثبيت من خلال النقر (CT)
• عمليات التثبيت من خلال النقر لعدة جلسات

هناك خياران لإعداد إحالة تثبيت Meta للحملات الإعلانية في تطبيق Android: الدمج المباشر أو الدمج المدعوم من خلال شريك قياس أداء تطبيقات الهواتف المحمولة (MMP).

الخيار الأول: الدمج المباشر

قبل البدء

قبل البدء، ستحتاج إلى ما يلي:

• إعداد مفتاح فك التشفير لإحالة تثبيت Google Play Install Referrer (GPIR)

الخطوة الأولى. إضافة تطبيقات Meta

أضف عناصر queries لتطبيقات فيسبوك وInstagram وFacebook Lite في ملف AndroidManifest.xml للسماح للتطبيق بالحصول على بيانات إسناد الإحالة من تطبيقات Meta هذه.

<queries>
  <package android:name="com.facebook.katana" />
</queries>

<queries>
  <package android:name="com.instagram.android" />
</queries>

<queries>
  <package android:name="com.facebook.lite" />
</queries>

الخطوة الثانية. تنفيذ ContentProvider API

أضف رمز ContentProvider للحصول على بيانات إسناد الإحالة من تطبيقات فيسبوك وInstagram. يجب الحصول على هذه البيانات عند إطلاق التطبيق لأول مرة.

Cursor c = null;
try {
    String [] projection = { "install_referrer", "is_ct", "actual_timestamp", };
    Uri providerUri = null;
    
    // This IF statement queries the facebook app first.
    // To query from the instagram app first, change the sequence of the IF statement

    if (context.getPackageManager().resolveContentProvider(
           "com.facebook.katana.provider.InstallReferrerProvider", 0) != null) {
       providerUri = Uri.parse(
           "content://com.facebook.katana.provider.InstallReferrerProvider/" + FB_APP_ID);
    } else if (context.getPackageManager().resolveContentProvider(
           "com.instagram.contentprovider.InstallReferrerProvider", 0) != null) {
       providerUri = Uri.parse(
           "content://com.instagram.contentprovider.InstallReferrerProvider/" + FB_APP_ID);
    } else if (context.getPackageManager().resolveContentProvider(
           "com.facebook.lite.provider.InstallReferrerProvider", 0) != null) {
       providerUri = Uri.parse("content://com.facebook.lite.provider.InstallReferrerProvider/" + FB_APP_ID);
    } else {
       return null;
    }

    c = context.getContentResolver().query(providerUri, projection, null, null, null);
    if (c == null || !c.moveToFirst()) {
       return null;
    }

    int installReferrerIndex = c.getColumnIndex("install_referrer");
    int timestampIndex = c.getColumnIndex("actual_timestamp");
    int isCTIndex = c.getColumnIndex("is_ct");
    String installReferrer = c.getString(installReferrerIndex); // serialized and encrypted attribution details

    // TODO: 
    // 1. deserialize installReferrer (convert String to JSON)
    // 2. decrypt attribution details in install_referrer.utm_content.source.data using 
    // key: GPIR decryption key 
    // nonce: retrieve from installReferrer.utm_content.source.nonce
    // data: retrieve from installReferrer.utm_content.source.data
    // decrypt data 

    long actualTimestamp = c.getLong(timestampIndex); // timestamp in seconds for click/impression
     int isCT = c.getInt(isCTIndex); // VT or CT, 0 = VT, 1 = CT
           
} catch (Exception e) {
    return null;
} finally {
    if (c != null) {
        c.close();
    }
}

تكون خطوات إلغاء تسلسل البيانات وفك تشفيرها مماثلة لتلك الموجودة في دليل إحالة التثبيت.

ستتضمن استجابة بنية البيانات التي تلقيتها من install_referrer بعد إلغاء التسلسل لكل تطبيق Meta ما يلي:

• actual_timestamp – القيمة هي الطابع الزمني بالثواني التي حدثت فيها النقرة أو مرة ظهور الإعلان
• is_ct - يمكن أن تكون القيمة 1 وتمثل عملية تثبيت النقر أو 0 وتمثل مرة ظهور إعلان
• install_referrer - تكون القيمة بينات إسناد إحالة تثبيت (GPIR) التي تم تشفيرها

مثال على الاستجابة باللغة JSON

{
  is_ct=1,
  actual_timestamp=123,
  install_referrer={
    utm_campaign = fb4a,
    utm_content: {
      source: {
        data: “7fb9bd76…”, // encrypted attribution information
        nonce: “1234” // nonce from encryption
      },
      a: <app_id>,
      t: <timestamp>
    }
    utm_source : “apps.facebook.com” //OR “apps.instagram.com”
  }
}

عينة من البيانات بعد إلغاء تشفير install_referrer.utm_content.source

{ 
  "ad_id":"6110809314024", 
  "adgroup_id":"6110808725024", 
  "adgroup_name":"RTG_Storie_", 
  "campaign_id":"6110808710224", 
  "campaign_name":"Mobex_Conversiones_Storie_Android_21 a 31 de Diciembre_OP39895",
  "campaign_group_id":"6110808710624", 
  "campaign_group_name":"Mobex_Instagram Storie_ Conversiones_ Diciembre OP 43918",
  "account_id":"485495091598353",
  "ad_objective_name":"CONVERSIONS", 
  // data included for Instagram ads
  "is_instagram":true,
  "publisher_platform":"instagram",                
  "platform_position":"instagram_stories"          
}

الخطوة الثالثة. إلغاء تكرار البيانات

إذا تم توفير بيانات تعريف الحملة الإعلانية لإحالة تثبيت GPIR، فيجب اتباع دفق إلغاء تكرار إحالة تثبيت GPIR الموجود.

إلغاء التكرار باستخدام إحالة التثبيت

يمكنك إزالة البيانات المتكررة باستخدام البيانات التي تم إرجاعها في install_referrer حيث إن القيم هي ذاتها بالنسبة لعملية التثبيت أو الحملة الإعلانية لعمليات التثبيت من خلال النقر عبر إحالة تثبيت Meta أو إحالة تثبيت GPIR.

بالنسبة إلى عمليات تثبيت العرض وعمليات التثبيت من خلال النقر لعدة جلسات، استخدم بيانات إحالة تثبيت Meta حيث إن إحالة تثبيت GPIR لا تدعمها.

إذا كانت بيانات التعريف للحملة الإعلانية لإحالة تثبيت GPIR غير موجودة، فيمكنك إلغاء تكرار البيانات استنادًا إلى ما إذا كنت تعمل مع شريك قياس أداء تطبيقات الهواتف المحمولة (MMP) أو لا.

إلغاء التكرار مع MMP

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

إلغاء التكرار بدون MMP

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

التحقق من الإعداد

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

• فيسبوك: الإصدار 428
• Instagram: الإصدار 296
• Facebook Lite: الإصدار 411

يمكنك التحقق من الإعداد عن طريق اتباع الخطوات التالية:

1. تضمين الحملة الاختبارية باستخدام المعاينة في مدير الإعلانات
2. البحث عن الإعلان في فيسبوك أو Instagram والنقر على الإعلان
3. إضافة نقاط التوقف أو السجلات في الرمز في الخطوة الثانية

من المفترض أن يتلقى التطبيق استجابة ويعمل على فك تشفيرها لعرض بيانات الحملة.

الخيار الثاني: الدمج المدعوم عبر قياس أداء تطبيقات الهواتف المحمولة (MMP)

الخطوة الأولى: تحديث مجموعة SDK قياس أداء تطبيقات الهواتف المحمولة (MMP)

تحديث مجموعة MMP SDK إلى إصدار يتضمن إحالة تثبيت Meta:

• مجموعة AppsFlyer SDK: مجموعة AppsFlyer SDK بالإصدار 6.14.2 والإصدارات الأحدث
• مجموعة Adjust SDK: مجموعة Adjust SDK بالإصدار 4.36.0 والإصدارات الأحدث (Flutter 4.36.0 والإصدارات الأحدث، Unity 4.37.0 والإصدارات الأحدث)
• مجموعة Singular SDK أو S2S API: مجموعة Singular SDK بالإصدار 12.3.0 والإصدارات الأحدث (Unity 4.2.0 والإصدارات الأحدث، React Native 3.3.0 والإصدارات الأحدث Unreal 2.2.0 والإصدارات الأحدث)
• مجموعة Kochava SDK: مجموعة Kochava Android SDK بالإصدار 5.1.0 والإصدارات الأحدث
• مجموعة Airbridge SDK: مجموعة Airbridge Android SDK بالإصدار 2.22.3 والإصدارات الأحدث
• مجموعة Branch SDK: مجموعة Branch SDK بالإصدار 5.10.1 والإصدارات الأحدث

الخطوة الثانية: التأكد من ربط معرف تطبيق فيسبوك بمجموعة MMP SDK

راجع التعليمات عبر الروابط أدناه.

• تعليمات ِAdjust
• تعليمات Singular
• تعليمات Kochava (الانتقال إلى قسم Meta/فيسبوك)
• تعليمات Airbridge
• يتعامل AppsFlyer مع ذلك تلقائيًا
• تعليمات Branch

الخطوة الثالثة: اعتمادًا على تطبيق قياس أداء تطبيقات الهواتف المحمولة (MMP)، قد تحتاج إلى تحديث ملف بيانات Android للتطبيق

راجع التعليمات عبر الروابط أدناه.

• تعليمات Kochava (الانتقال إلى قسم Meta/فيسبوك)
• تعليمات Branch
• تتعامل AppsFlyer وAdjust وSingular وAirbridge تلقائيًا مع هذه الخطوة عبر مجموعة SDK
• يُرجى التحقق من قياس أداء تطبيقات الهواتف المحمولة إذا كنت تستخدم مجموعات Flutter / React بدلاً من مجموعات Android SDK

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

ملاحظة: إذا قمت بالفعل بإجراء ذلك لإحالة تثبيت متجر Google Play، فهذه الخطوة غير ضرورية.

• ستحتاج إلى صلاحية وصول المسؤول إلى حساب مدير الأعمال الذي يملك التطبيق.
• قم بتسجيل الدخول إلى Meta للمطوّرين.
• انتقل إلى تطبيقاتي في أعلى الجانب الأيسر.
• حدد التطبيق الذي ترغب في الوصول إلى مفتاح فك التشفير الخاص بك.
• حدد إعدادات التطبيق > الإعدادات الأساسية.
• مرر لأسفل إلى قسم Android. ابحث عن مفتاح فك تشفير إحالة التثبيت ضمن تصنيف متجر Google Play.
• شارك مفتاح فك التشفير مع تطبيق قياس أداء تطبيقات الهواتف المحمولة (MMP). راجع التعليمات عبر الروابط أدناه.
  

  • تعليمات AppsFlyer
  • تعليمات Adjust
  • تعليمات Singular
  • تعليمات Kochava
  • تعليمات Airbridge
  • تعليمات Branch