Реферер установок Meta

В этом документе рассказывается, как использовать реферер установок Meta в приложениях Android, чтобы получать метаданные рекламных кампаний на Facebook, в Instagram и в Audience Network, целью которых является установка приложения. В то время как реферер установок Google Play (GPIR) предоставляет информацию только для одного сеанса, реферер установок Meta позволяет получать информацию о:

• просмотре установок (VT);
• нажатии установок (CT);
• нажатии установок в нескольких сеансах.

Существует два способа настройки реферера установок Meta для рекламных кампаний в Android: прямая интеграция и поддерживаемая интеграция с помощью партнеров по мобильным измерениям.

Вариант 1. Прямая интеграция

Прежде чем начать

Вам понадобится:

• настроенный ключ дешифровки для реферера установок Google Play .

Шаг 1. Добавление приложения Meta

Добавьте элементы queries для приложений Facebook, 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>

Шаг 2. Внедрение ContentProvider API

Добавьте код ContentProvider, чтобы получать реферальные данные атрибуции от приложений Facebook и 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"          
}

Шаг 3. Дедупликация данных

Если метаданные GPIR для рекламной кампании доступны, следуйте своему существующему процессу дедупликации GPIR.

Дедупликация с помощью реферера установок

Чтобы удалить дублирующиеся данные, можно использовать данные, возвращаемые в install_referrer, поскольку значения для установки или кампании для CT в реферере установок Meta и в GPIR одинаковы.

Для VT и CT с несколькими сеансами используйте данные реферера установок Meta, поскольку GPIR их не поддерживает.

Если метаданные GPIR для рекламной кампании отсутствуют, дедуплицируйте данные в зависимости от того, работаете ли вы с партнером по мобильным измерениям (MMP).

Дедупликация с помощью MMP

Партнеры по мобильным измерениям имеют доступ на уровне строк к данным атрибуции для установок, у которых нет выигравшей рекламной сети (они либо атрибутированы Meta, либо это органические установки). Вы можете проверить, есть ли в них реферер установок, предоставленный через реферер установок Meta. Если да, то можно считать, что установка организована Meta, и предоставленные данные реферера установок являются метаданными рекламной кампании для установки.

Дедупликация без MMP

Реферер установок Meta предоставляет информацию о последней операции установки, в том числе метаданные рекламной кампании, метку времени последней операции и тип действия последней операции (показ или нажатие). Вы можете сравнить тип действия и метку времени последней операции с данными атрибуции, полученными от других рекламных сетей, и определить победившую рекламную сеть.

Проверка установки

Сначала убедитесь, что используемая версия приложения поддерживает это решение. Минимальные номера версий:

• Facebook — v428;
• Instagram — v296;
• Facebook Lite — 411.

Чтобы проверить установку, выполните следующие действия:

1. Запустите тестовую кампанию через предпросмотр в Ads Manager.
2. Найдите рекламу на Facebook или в Instagram и нажмите ее.
3. Добавьте в свой код на шаге 2 точки останова или регистрацию.

Для просмотра данных кампании ваше приложение должно получить ответ и дешифровать его.

Вариант 2. Поддерживаемая интеграция с помощью партнера по мобильным измерениям

Шаг 1. Обновление SDK партнера по мобильным измерениям

Обновите 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 и более поздних.

Шаг 2. Проверка связи ID приложения Facebook с SDK партнера по мобильным измерениям

См. инструкции по ссылкам ниже.

• Инструкции для Adjust
• Инструкции для Singular
• Инструкции для Kochava (перейдите в раздел Meta/Facebook)
• Инструкции для Airbridge
• В AppsFlyer всё выполняется автоматически
• Инструкции для Branch

Шаг 3. Обновление файла Manifest Android для вашего приложения (в зависимости от партнера по мобильным измерениям)

См. инструкции по ссылкам ниже.

• Инструкции для Kochava (перейдите в раздел Meta/Facebook).
• Инструкции для Branch
• AppsFlyer, Adjust, Singular и Airbridge автоматически выполняют этот шаг через свои SDK
• Если вы используете Flutter или React SDK, а не Android SDK, обратитесь к своему партнеру по мобильным измерениям

Шаг 4. Передача ключа дешифровки для реферера установок, чтобы партнер по мобильным измерениям мог расшифровывать метаданные реферера

Примечание. Если вы уже сделали это для реферера установок Google Play, этот шаг выполнять не нужно.

• Вам потребуется доступ администратора к аккаунту Business Manager, которому принадлежит приложение.
• Войдите в Meta for Developers.
• Перейдите в Мои приложения в правом верхнем углу.
• Выберите приложение, в котором вы хотите получить доступ к ключу дешифрования.
• Выберите Настройки приложения > Основные.
• Прокрутите вниз до раздела Android. Найдите ключ дешифровки для реферера установок под ярлыком Google Play.
• Передайте ключ дешифровки своему партнеру по мобильным измерениям. См. инструкции по ссылкам ниже.
  

  • Инструкции для AppsFlyer
  • Инструкции для Adjust
  • Инструкции для Singular
  • Инструкции для Kochava
  • Инструкции для Airbridge
  • Инструкции для Branch