API d'événements de serveur à serveur pour mobile (S2S mobile)

En bref : utilisez l'API mobile d'événements de serveur à serveur (S2S) pour envoyer à AppsFlyer les événements qui se produisent en dehors de votre app. Les événements S2S sont attribués de la même manière que les événements SDK et sont disponibles sur toute la plate-forme.  

S2S_us-en.png

API pour mobile d'événements de serveur à serveur

La plateforme AppsFlyer attribue et enregistre les événements d'apps mobile qui sont envoyés par le SDK AppsFlyer et par les API. Utilisez l'API S2S pour signaler les événements qui ont lieu hors de l'app, par exemple pour un utilisateur qui renouvellerait son abonnement en utilisant votre interface web. Une fois enregistrés, les événements S2S sont disponibles sur toute la plateforme, y compris les tableaux de bord, les données brutes et les analyses. Pour les événements web de PBA, consultez Le S2S mobile pour la PBA.

AppsFlyer remplit les événements S2S en se basant sur :

  • Les valeurs envoyées dans le message S2S
  • Certaines AppsFlyer valeurs d'attribution d'installation AppsFlyer, comme l'heure ou la source du média.

Instructions d'utilisation de l'API

Créez l'appel de votre API en utilisant les informations contenues dans les chapitres suivants. 

Éléments de code API S2S

Point de terminaison API

https://api2.appsflyer.com/inappevent/app_id

  • app_id: identifiant d'app utilisé dans le tableau de bord AppsFlyer. Vous devez l'insérer exactement tel qu'affiché dans le tableau de bord.
  • Apps iOS : n'oubliez pas d'ajouter le préfixe id. Sans ce préfixe, le code retour 200 OK sera valide mais l'événement ne sera pas enregistré.
  • Windows : l'ID d'app se trouve dans le Microsoft App Store.
  • Exemple Android : https://api2.appsflyer.com/inappevent/com.appsflyer.myapp
    iOS :https://api2.appsflyer.com/inappevent/id123456789
    Windows :https://api2.appsflyer.com/inappevent/a1b2c3d4e5f6
Méthode HTTP POST
Type de contenu accepté application / json
Autorisation

--header 'authentication: dev_key'

  • dev_key correspond au jeton d'authentification dans le «header». 
  • Pour obtenir la clé dev, rendez-vous dans AppsFlyer et suivez Paramètres de l'app > Clé dev
Liste des serveurs autorisés (Allowlist) pour recevoir les messages de réponse

Mettez sur la liste des serveurs autorisés (Allowlist) les  plages d'adresses IP AWS pour recevoir les messages de réponse si vos serveurs sont protégés par un pare-feu. 

Limitation de charge utile JSON

Charge utile JSON : maximum 1 KB

Limitation de taux

Volume maximum de POST : 60 000 POST par minute. Pour dépasser ce taux, veuillez contacter votre CSM.

Instructions de codage
Encoder les URL

Encodez la portion de code (en %) attribuée aux caractères (https://tools.ietf.org/html/rfc3986#section-2.1) avant de former l'URL de méthode. 

Protocole TLS

Utilisez le protocole TLS 1.2 ou +. Signes et caractères pris charge

Éléments de code API S2S

Paramètres de charge utile

  • Les paramètres de charge utile sont constitués d'un ou plusieurs identifiants d'appareil (selon le système d'exploitation).
  • Que se passe-t-il si je ne parviens pas à envoyer l'identifiant d'un appareil?
    • Vous pouvez être dans l'impossibilité d'envoyer l'identifiant pour une raison qui ne vous appartient pas, par exemple l'utilisateur a activé le suivi limité des publicités (LAT) ou bien il utilise iOS 14 et a refusé l'ATT (pas d'IDFA).
    • Si cela se produit, sachez que si l'envoi d'un ID publicitaire/d'appareil ne se fait pas, l'attribution peut échouer,ce qui signifie qu'AppsFlyer ne pourra pas attribuer l'événement à la source média. Les évènements sont enregistrés et s'affichent bien dans les rapports et les tableaux de bord.
Système d'exploitation Nom de l'identifiant Description

iOS

iconAFios.png

 

idfa 

Si disponible, à remplir avec l'IDFA de l'appareil

Format : chaîne

Exemple :  "idfa": "9876F1SS-2983-3855-27RR-2R626772VFNB"

idfv

Si disponible, à remplir avec l'IDFV de l'appareil.

Format : chaîne
Exemple :  "idfv": "95C9BD22-4A4C-41C8-9548-ED07C5C8C145"

Android

iconAFand.png

advertising_id

Si disponible, à remplir avec le GAID de l'appareil (ID publicitaire)

Format : chaîne

Exemple : "advertising_id": "9c9a82fb-d5de-4cd1-90c3-527441c11828"

oaid

Format : chaîne

Exemple : "oaid" : " 1fe9a970-efbb-29e0-0bdd-f5dbbf751ab5"

amazon_aid

Format : chaîne

imei

Format : chaîne

Exemple : "imei": "AA-BBBBBB-CCCCCC-D"

Identifiants d'appareil
Nom du paramètre Obligatoire Description

appsflyer_id

Oui

Un identifiant unique généré par AppsFlyer lorsque l'app est lancée pour la première fois. 

  • Format : chaîne
  • Exemple : "appsflyer_id": "1415211453000-6513894"

customer_user_id

Non

ID utilisateur du client, un identifiant utilisateur unique défini par le propriétaire de l'app.

  • Format :  chaîne. 
  • Exemple : "customer_user_id": "my_customer_number1234" 

att

Non

Statut d'autorisation ATTrackingManager IOS

  • Si le système d'exploitation de l'appareil date de la version iOS 14 ou +, vous devez renseigner ATTrackingManager.
    • Format : nombre entier à un chiffre 
    • Exemple : 1
  • Les valeurs iOS pour ATTrackingManager sont :
    • 0 : non déterminé
    • 1 : limité
    • 2 : refusé
    • 3 : autoriser

Remarque 

  • Dans le cadre de la politique de confidentialité d'Apple, nous vous recommandons de remplir att avec la valeur ATTrackingManager.
  • Vous pouvez envoyer ce paramètre avant le lancement officiel de l'iOS14 ; nous commencerons à le traiter après le lancement officiel.

 

ip

Non

L'adresse IP de l'appareil mobile lorsque l'événement se produit.

  • Si elle est envoyée, l'adresse IP est utilisée pour peupler les champs géographiques.
  • Si elle n'est pas envoyée, AppsFlyer remplit l'adresse IP et les champs géographiques en utilisant les valeurs de l'événement d'attribution d'installation. 
  • Format : chaîne contenant une adresse IPV4 ou IPV6
  • Exemple : « ip » : "192.0.2.1
af_events_api Obsolète
  • Obsolète à partir du 6 juillet 2020.
  • Il n'y a pas besoin de ce paramètre, vous pouvez arrêter de l'envoyer. Cela n'aura aucune incidence sur l'attribution. 

eventName

Oui

Spécifie le nom de l'événement. Veillez à ce que les noms d'événement soient conformes aux exigences du marketeur.

  • Format : chaîne
  • Exemple : "eventName": "af_purchase"

Valeur de l'événement

Oui

Dans le cas où vous envoyez un événement sans valeur, envoyez : "event_value":""

  • Les valeurs d'événement doivent être envoyées sans symboles ni mise en forme supplémentaires.
  • Pour af_revenue, la décimale après virgule est autorisée. Les valeurs négatives doivent être précédées d'un - 
  • Format : chaînes en JSON
  • Exemple : "eventValue": "{ \"af_revenue\": \"6\", \"af_content_type\": \"wallets\", \"af_content_id\": \"15854\", \"af_quantity\" :\"1\" }"

app_version_name

Non

La version ou l'identifiant de votre app.

  • Format : chaîne
  • Exemple: "app_version_name": "my_app_version"

app_store

Non

Equivalent à AF_STORE pour les apps Android. Le store où l'application a été téléchargée. 

  • Champ de données brutes : installation de l'App Store
  • Format : chaîne
  • Exemple : my_android_store_is_best

Heure de l'évènement

Non

L'heure à laquelle l'événement s'est produit (format UTC).

  • Par défaut : si aucun eventTime n'est envoyé, l'heure définie correspond à l'heure d'arrivée du message HTTP.
  • Format : chaîne aaaa-mm-jj hh:mm:ss.sss l'heure doit être dans le fuseau horaire UTC.
  • Exemple : "eventTime":"2019-05-15 12:17:01.123" signifie 12 h 17 mn 01 s (format UTC). 

Clôture de journée :

  • Si vous implémentez eventTime, l'événement doit être reçu par AppsFlyer au plus tard à 02 h le lendemain. Ce qui signifie que si l'événement a eu lieu le lundi à 17:00 UTC, il doit atteindre les serveurs d'AppsFlyer au le mardi à 02:00 UTC au plus tard. 
  • Les événements reçus après la clôture de journée seront datés à l'heure d'arrivée effective.
  • Les événements ayant une heure future, c'est-à-dire après l'heure d'arrivée, sont horodatés à l'heure d'arrivée. 

Exemple

  • Les heures sont en UTC
  • Un événement est envoyé avec eventTime = Lundi 21h00.
Heure d'arrivée Heure enregistrée par AppsFlyer Remarque
Mardi 01h00 Lundi 21h00 Arrivée avant l'heure de fermeture.
Mercredi 09h00  Mercredi 09h00 Arrivée après l'heure de fermeture. L'heure est définie à l'heure d'arrivée. 

eventCurrency

Non

Code de devise selon les normes ISO 4217 à 3 caractères et BCN (Bitcoin)

  • Par défaut : USD
  • Exemple : "eventCurrency": "ZAR"

bundleIdentifier

Non

Un identifiant unique de l'app. Dans les données brutes, le paramètre renseigne l'ID de groupe.

  • Format : chaîne
  • Exemple : "bundleIdentifer": "com.myapp"

sharing_filter

Non

Le filtre de partage bloque le partage d'événements S2S via postback/API avec les partenaires intégrés et autres intégrations tierces.

Utilisez ce filtre pour répondre aux réglementations telles que le RGPD et la CCPA, pour vous conformer aux actions de retrait des utilisateurs ou pour tout autre logique commerciale. 

Le sharing_filter offre les options suivantes :

  • all : tous les partenaires sont bloqués. L'événement n'est partagé avec personne.Exemple : "sharing_filter": "all"
  • Liste des identifiants de partenaires. Format ["partnerid_1", "partnerid_2", "partnerid_n"]  Exemple : "sharing_filter": ["googleadwords_int", "adcolony_int"]

Pour obtenir la liste des identifiants de partenaire, contactez votre MSC ou l'assistance AppsFlyer.

custom_dimension

Non

Reserved for AppsFlyer future use

Exemple en curl

curl --location --request POST 'https://api2.appsflyer.com/inappevent/<app_id_placeholder>' \
--header 'authentication: <dev_key_placeholder>
' \
--header 'Content-Type: application/json' \
--data-raw '{
  "appsflyer_id": "9999999999999-9999999999999999999",
	"advertising_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
	"customer_user_id" : "example_customer_id_123",
	"ip": "199.0.2.1",
	"app_version_name" : "example_version_name",
	"eventTime" : "2020-02-25 12:00.000",
	"eventName": "af_purchase",
	"eventCurrency": "ZAR",
	"eventValue": 
	"{
		\"af_revenue\": \"1006\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }"
}
'

Codes de réponse

Code de réponse  Message Gestion
200 OK

À réception du message, une vérification minimum des données est effectuée. Vous pouvez donc recevoir une réponse OK même si l'événement n'a pas été totalement enregistré dans AppsFlyer. Pour déboguer les événements :

  • En utilisant l'exemple CURL inclus dans ce chapitre"
    • Mettez à jour les infos de l'id d'app de la dev key.
    • Modifiez les paramètres appsflyer_id et eventTime. Utilisez l'heure en cours ainsi qu'un appsflyer_id récemment attribué comme non organique.
  • Envoyez l'appel.
    • Le message de retour devrait être un OK 200.
    • Vérifiez si l'événement a été enregistré correctement, y compris les revenus
    • Apportez les modifications éventuellement requises puis relancez un test.
400 Échec de l'authentification Assurez-vous que la clé d'authentification est correcte.
400  appsflyer_id est un champ obligatoire
  •  Assurez-vous que l'ID AppsFlyer du JSON est correct.
  • JSON a été converti en chaîne() et son format est correct.
401 Non autorisé Lorsque la clé fournie dans l'en-tête d'authentification n'est pas la <dev_key> de cette app.
400 Demande incorrecte.

Lorsqu'au moins un des critères de validation a échoué pour la requête.

400  Charge utile absente ou échec de l'analyse
  • Assurez-vous que le JSON a été converti en chaîne et que son format est correct.
  • Si plus d'un événement est inclus dans la charge utile JSON. Assurez-vous d'envoyer un seul événement par requête.
500  Erreur interne du serveur  Vérifiez le JSON a été converti en chaîne() et que son format est correct.
 

Test

Important :

  • Pour le test, utilisez l'ID AppsFlyer d'une installation non organique afin que les attributs de l'événement testé soient pris en temps réel. Les événements organiques sont attribués avec un décalage de quelques heures.
  • Certains champs d'un événement sont remplis en utilisant l'événement d'attribution d'installation de l'utilisateur. Par exemple, l'heure d'installation et la source média.

Pour attribuer l'appareil de test comme installation non organique :

  1. Préparez un lien d'attribution personnalisé pour tester les messages S2S. Définissez le paramètre de source média du lien sur s2s_test. Exemple : &pid=s2s_test 
  2. Enregistrer l'appareil de test
  3. Désinstallez l'app de l'appareil de test.
  4. Envoyez le lien vers l'appareil de test.
  5. Cliquez sur le lien.
  6. Installez l'application puis lancez-la.
  7. Dans le tableau de bord, vérifiez que l'installation est bien attribuée.
  8. Extrayez l'ID d'appareil AppsFlyer qui sera utilisé pour vos messages S2S.

Pour envoyer le message de test S2S :

  1. Préparez un message S2S avec l'ID AppsFlyer alloué. Consultez les exemples de code ci-dessous.
  2. Envoyez le message.
  3. Réalisez l'une des opérations suivantes pour voir comment le message est enregistré dans AppsFlyer :
  4. Vérifiez que :
    • Les valeurs envoyées dans le message S2S apparaissent bien dans le rapport. Portez une attention particulière aux champs Date de l'événement, Devise de l'événement, Revenus de l'événement et Valeur de l'événement.
    • Les sources d'attribution et les heures d'installation sont renseignées par AppsFlyer.
    • Les valeurs fournies par le SDK lui-même, comme la version SDK, ne sont pas complétées.

Exemple de code pour l'envoi de messages S2S

JavaPythonNode JSC#PHPGo
/* using the okhttp package 
install from maven https://mvnrepository.com/artifact/com.squareup.okhttp3/okhttp */
import okhttp3.*;
import java.io.IOException;

public class SendRequest {
  public static void main(String[] args) {

    OkHttpClient client = new OkHttpClient();
    MediaType mediaType = MediaType.parse("application/json");

    RequestBody body = RequestBody.create(mediaType, "" +
        "{\r\n\t\"appsflyer_id\": \"<APPS_FLYER_ID>\"," +
        "\r\n\t\"customer_user_id\": \"123456\",\r\n\t\"eventName\": \"af_purchase\",\r\n\t\"" +
        "eventValue\": \"{\\\"af_revenue\\\":\\\"6\\\" ,\\\"af_content_id\\\":\\\"15854\\\"}\",\r\n\t\"" +
        "eventCurrency\": \"USD\",\r\n\t\"" +
        "eventTime\": \"2018-08-10 4:17:00.000\",\r\n\t\"");

    Request request = new Request.Builder()
        .url("https://api2.appsflyer.com/inappevent/<APP_ID>")
        .post(body)
        .addHeader("Content-Type", "application/json")
        .addHeader("authentication", "<YOUR_DEV_KEY>")
        .build();

    try {
      Response response = client.newCall(request).execute();
      System.out.println(response.code());
      System.out.println(response.body().string());
    } catch (IOException e) {
      e.printStackTrace();
    }
  }
}

Il est important d'envoyer l'ID de l'appareil ou l'ID de publicité

  • L'ID de publicité / l'identifiant d'appareil est obligatoire pour garantir les postbacks envoyés aux SRN comme Facebook et Google Ads. Si vous ne pouvez pas envoyer l'ID, sachez que les postbacks ne pourront pas être envoyés.
  • Si vous n'envoyez que l'identifiant AppsFlyer, les événements in-app seront enregistrés et attribués correctement.

Paramètres de remplissage

Différence entre organique et non organique

Lorsque AppsFlyer traite des événements in-app S2S, les champs d'attribution sont remplis en se basant sur l'ID AppsFlyer afin d'identifier l'événement d'installation qui a précédé les événements in-app.

Cela signifie que certaines données qu'AppsFlyer associe à des événements in-app S2S non organiques ne sont pas associées à des événements in-app S2S organiques.

 Exemple

Par exemple, si vous comparez les rapports de données brutes d'événements in-app S2S non organiques et organiques, les événements non organiques contiennent des données que les événements in-app organiques ne contiennent pas.

Les événements in-app non organiques incluent les données concernant la source média, la campagne, le type de touch attribué et l'heure du touch attribué.

Les événements in-app organiques quant à eux suivent une installation organique. Les installations organiques ne disposent pas de données relatives à la campagne ou source média, ni au type ou à l'heure de touch attribué.

Mappage de l'ID AppsFlyer avec l'ID utilisateur du client (CUID)

Une démarche en arrière-plan est requise pour obtenir les valeurs permettant de renseigner les paramètres. Vous trouverez ci-dessous comment obtenir l'ID AppsFlyer :

  • L'ID AppsFlyer est obligatoire et sert à attribuer les événements.
  • Il est généré dès qu'un utilisateur installe une app mobile pour la première fois.
  • Pour pouvoir mapper votre CUID avec l'ID AppsFlyer, vous devez définir le CUID au sein de l'app.

Pour connaître plus facilement l'utilisateur à l'origine de chaque évènement, procédez comme suit :

  • Définissez l'ID utilisateur du client lorsque l'utilisateur installe l'app.
  • Les rapports de données brutes AppsFlyer contiennent le CUID et l'ID AppsFlyer. Pour l'obtenir, utilisez l'un des outils de livraison de données ou bien l'API Push AppsFlyer.
  • Utilisez les rapports de données brutes pour comparer le CUID et l'ID AppsFlyer. 
  • L'ID AppsFlyer est disponible dans le SDK intégré à votre app (Android / iOS).
  • Mappez l'ID AppsFlyer avec l'ID utilisateur du client dans vos systèmes internes (très important pour les futures utilisations).

Après avoir mappé l'ID AppsFlyer à votre CUID, vous pourrez facilement associer chaque utilisateur avec les événements qu'il a exécutés. Vous pourrez ensuite obtenir d'autres valeurs (valeur d'évènement, devise d'évènement, heure de l'évènement, etc.), puis envoyer l'évènement in-app de serveur à serveur. 

 Exemple de corps de requête

{
  "appsflyer_id": "1415211453000-6513894",
	"advertising_id": "38412345-8cf0-aa78-b23e-10b96e40000d",
	"eventName": "af_purchase",
	"eventValue": 
	"{
		\"af_revenue\": \"6\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }",
	"eventCurrency": "USD",
	"ip": "1.2.3.4",
	"eventTime": "2014-05-15 12:17:00.000"
}


Dans ce cas, AppsFlyer reçoit un événement in-app S2S qui représente un événement d'achat avec revenu, ainsi que des propriétés supplémentaires telles que le type de contenu, etc.

Récupérer l'ID AppsFlyer

appsflyer_id est un paramètre obligatoire dans les messages d’événement de serveur à serveur. AppsFlyer utilise ce paramètre pour attribuer l’événement à l’appareil d’origine et à la source média attribuée. Vous pouvez définir l’ID utilisateur en appliquant l'une des méthodes suivantes :

 Astuce

Lorsque vous testez les messages S2S, si vous utilisez des données brutes recherchez l'enregistrement dont la source média est signalée par « s2s_test ». Il s’agit de votre appareil de test et son ID d'appareil AppsFlyer est l’identifiant dont vous avez besoin.

Envoi de revenus négatifs

Les événements qui ont une valeur négative de revenus peuvent être envoyés. Par exemple, dans le cas où un achat a été annulé. Le paramètre af_revenue peut avoir des valeurs négatives pour permettre l'enregistrement.

Lorsque vous remplissez af_quantity, vous pouvez avoir besoin de renseigner une valeur négative en fonction du fonctionnement de votre système. AppsFlyer n'utilise pas af_quantity.

Exemple contenant des revenus négatifs

{
	"eventName": "cancel_purchase",
	"eventValue": 
	"{
		\"af_revenue\": \"-6\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }",
	"eventCurrency": "USD",
	
}

Envoi d'événements sans valeur d'événement

Si vous souhaitez envoyer des événements sans valeur d'événement, transmettez simplement une chaîne vide à la valeur d'événement : "event_value": ""

AppsFlyer est alors en mesure, selon la configuration de l’annonceur, d’envoyer de tels événements rich in-app aux sources médias aux fins de ciblage avancé, d'optimisation et de création de public.

Dépannage

Les événements ne s'affichent pas dans le tableau de bord

  • Point de terminaison : vérifiez que le point de terminaison est utilisé proprement.
  • Vérifiez que la charge utile contient bien les paramètres obligatoires. Plus d'infos ici.
  • Vérifiez que l'ID AppsFlyer que vous utilisez pour amorcer l'événement est un véritable appsflyer_id, et qu'il est bien installé sur l'app concernée. Veuillez à ne pas utiliser un ID factice comme on peut en trouver dans les exemples. Plus d'infos ici.
  • Les événements S2S ne prennent pas en charge l'envoi d'événements multiples sur une seule requête S2S. Chaque événement doit obligatoirement être envoyé un par un. 
  • Dans le tableau de bord général, la plage de dates se rapporte au jour d'installation de l'app (LTV), et non au jour de l'événement.
    • Veillez à sélectionner la bonne période.
    • Assurez-vous que la plage de dates du tableau de bord correspond bien à la date d'installation de l'appareil (appsflyer_id), et non à la date de l'événement.
  • Rapports de données brutes d'événements : la plage de dates se rapporte au jour de l'événement et non au jour d'installation.

Les événements ne contiennent pas de revenu

Si vous envoyez des événements S2S dont les revenus ne sont pas enregistrés : veillez à ce que le JSON que vous envoyez soit converti en chaîne. La section la plus importante est celle du paramètre de valeur d'événement dans le JSON. Elle doit être convertie en chaîne comme stipulé dans l'exemple suivant.

"{\"af_revenue\":\"6\" ,\"af_content_type\":\"wallets\"}"

Dans le cas contraire, la valeur de l'événement ne sera pas traitée correctement et ne pourra pas être enregistrée.

Les valeurs de revenus ne doivent absolument pas être formatées. Elles peuvent contenir une virgule, mais ce n'est pas obligatoire. N'y ajoutez aucun signe, code de devise ou séparateur. Les revenus peuvent être précédés d'un -

  • Exemples de valeurs valides : 123, -123.45123.456 
  • Exemples de valeurs invalides : 1,234.561,234

Dans les événements S2S, tous les champs ne sont pas remplis

Les champs de données brutes sont renseignés à l'aide de la valeur transmise dans l'appel S2S, tandis que d'autres champs sont remplis à l'aide de l'événement d'installation.  On observe la même chose, à quelques exceptions près, pour les événements in-app signalés à l'aide du SDK AppsFlyer. Il existe quelques différences entre les deux, notamment, les champs suivants ne sont pas renseignés pour les événements S2S :

  • wifi
  • operator
  • langue
  • Type d'appareil
  • Catégorie d'appareil
  • Version de l'app : vous pouvez utiliser app_version_name
  • Nom de l'app
Cet article vous a-t-il été utile ?