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.
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 |
|
| Méthode HTTP | POST |
| Type de contenu accepté | application / json |
| Autorisation |
|
| Liste des serveurs autorisés (Allowlist) pour recevoir les messages de réponse | |
| 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 |
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 c'est le cas, sachez que le défaut d'envoi d'un ID publicitaire ou ID d'appareil peut entraîner :
- L'échec de l'attribution, ce qui signifie qu'AppsFlyer n'est pas en capacité d'attribuer l'événement à la source média. Les événements sont enregistrés et s'affichent bien dans les rapports et tableaux de bord.
- Segmentation des audiences et échec des règles. Les ensembles de règles pour les audiences requièrent des identifiants. Fournissez un ID d'appareil ou un ID utilisateur du client en fonction du type d'ID que votre ensemble de règles utilise.
| Système d'exploitation | Nom de l'identifiant | Description |
|---|---|---|
|
iOS
|
idfa |
Si disponible, à remplir avec l'IDFA de l'appareil Format : chaîne Exemple : |
| idfv |
Si disponible, à remplir avec l'IDFV de l'appareil. Format : chaîne |
|
|
Android
|
advertising_id |
Si disponible, à remplir avec le GAID de l'appareil (ID publicitaire) Format : chaîne Exemple : |
| oaid |
Format : chaîne Exemple : |
|
| amazon_aid |
Format : chaîne |
|
| imei |
Format : chaîne Exemple : |
| 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.
|
|||||||||
|
customer_user_id |
Non |
ID utilisateur du client, un identifiant utilisateur unique défini par le propriétaire de l'app.
|
|||||||||
|
att |
Non |
Statut d'autorisation ATTrackingManager IOS
Remarque
|
|||||||||
|
ip |
Non |
L'adresse IP de l'appareil mobile lorsque l'événement se produit.
|
|||||||||
| Obsolète |
|
||||||||||
|
eventName |
Oui |
Spécifie le nom de l'événement. Veillez à ce que les noms d'événement soient conformes aux exigences du marketeur.
|
|||||||||
|
Valeur de l'événement |
Oui |
Dans le cas où vous envoyez un événement sans valeur, envoyez :
|
|||||||||
|
app_version_name |
Non |
La version ou l'identifiant de votre app.
|
|||||||||
|
app_store |
Non |
Equivalent à AF_STORE pour les apps Android. Le store où l'application a été téléchargée.
|
|||||||||
|
Heure de l'évènement |
Non |
L'heure à laquelle l'événement s'est produit (format UTC).
Clôture de journée :
Exemple
|
|||||||||
|
eventCurrency |
Non |
Code de devise selon les normes ISO 4217 à 3 caractères et BCN (Bitcoin)
|
|||||||||
|
bundleIdentifier |
No* |
A unique app identifier. In raw-data, the parameter populates Bundle ID. [Best practice] Always populate this parameter. Many ad networks require it for campaign optimization.
|
|||||||||
|
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 :
Pour obtenir la liste des identifiants de partenaire, contactez votre MSC ou l'assistance AppsFlyer. |
|||||||||
|
custom_dimension |
Non |
Prévu pour une future utilisation AppsFlyer |
|||||||||
|
app_type |
Non |
Pour les apps iOS. Valeur autorisée : Si l'événement utilisateur se produit dans un fichier app_clip, envoyez le paramètre. Dans tous les autres cas, n'envoyez pas le paramètre. |
|||||||||
|
* Required by many ad networks for optimization purposes |
|||||||||||
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 :
|
| 400 | Échec de l'authentification | Assurez-vous que la clé d'authentification est correcte. |
| 400 | appsflyer_id est un champ obligatoire |
|
| 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 |
|
| 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 :
- 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 - Enregistrer l'appareil de test
- Désinstallez l'app de l'appareil de test.
- Envoyez le lien vers l'appareil de test.
- Cliquez sur le lien.
- Installez l'application puis lancez-la.
- Dans le tableau de bord, vérifiez que l'installation est bien attribuée.
- Extrayez l'ID d'appareil AppsFlyer qui sera utilisé pour vos messages S2S.
Pour envoyer le message de test S2S :
- Préparez un message S2S avec l'ID AppsFlyer alloué. Consultez les exemples de code ci-dessous.
- Envoyez le message.
- Réalisez l'une des opérations suivantes pour voir comment le message est enregistré dans AppsFlyer :
- Download the in-app events raw data report. Allow up to 15 minutes after sending the event for it to show up in the raw data report.
- Lancez l'API Push (pensez également aux outils du genre Postman ou Webhook site.)
- 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
/* 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();
}
}
}
''' using the requests python package, install using pip install requests '''
import requests
url = "https://api2.appsflyer.com/inappevent/[Insert app ID here]"
payload = "{\r\n \"appsflyer_id\": \"9999999999999999999999\",\r\n\t\"IDFA\":\"999999999999999999999999\",\r\n\t\"customer_user_id\" : \"14mar\",\r\n\t\"ip\": \"10.0.0.1\",\r\n\t\"app_version_name\" : \"example_version_name\",\r\n\t\"eventTime\" : \"2020-04-25 08:59:01.23\",\r\n\t\"eventName\": \"gaf_purchase\",\r\n\t\"eventCurrency\": \"ZAR\",\r\n\t\"eventValue\": \r\n\t\"{\r\n\t\t\\\"af_revenue\\\": \\\"1000\\\",\r\n\t\t\\\"af_content_type\\\": \\\"wallets\\\",\r\n\t\t\\\"af_content_id\\\": \\\"15854\\\",\r\n\t\t\\\"af_quantity\\\" :\\\"1\\\"\r\n }\"\r\n}"
headers = {
'authentication': '[Insert web dev key]',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data = payload)
print(response.text.encode('utf8'))
/* using the request npm package, install using npm install request */
var request = require("request");
var options = { method: 'POST',
url: 'https://api2.appsflyer.com/inappevent/<APP_ID>',
headers:
{
"authentication": '<YOUR_DEV_KEY>',
'Content-Type': 'application/json'
},
body:
{ appsflyer_id: '<APPS_FLYER_ID>',
customer_user_id: '123456',
eventName: 'node_js',
eventValue: '{"node_js":"6" ,"af_content_id":"15854"}',
eventCurrency: 'USD',
ip: '1.0.0.0',
eventTime: '2018-07-09 4:17:00.000'
},
json: true };
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});/* using the RestSharp package, install using NuGet */
using System;
using RestSharp;
namespace CS
{
class Event
{
static void Main(string[] args)
{
var client = new RestClient("https://api2.appsflyer.com/inappevent/<APP_ID>");
var request = new RestRequest(Method.POST);
request.AddHeader("authentication", "<YOUR_DEV_KEY>");
request.AddHeader("Content-Type", "application/json");
var body = "{\"appsflyer_id\": \"<APPS_FLYER_ID>\"," +
"\"customer_user_id\": \"123456\"," +
"\"eventName\": \"af_purchase\"," +
"\"eventValue\": \"{\\\"af_revenue\\\":\\\"6\\\" ,\\\"af_content_id\\\":\\\"15854\\\"}\"," +
"\"eventCurrency\": \"USD\"," +
"\"eventTime\": \"2018-07-08 4:17:00.000\"
}";
request.AddParameter("undefined", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
// handle response by reading response.StatusCode
Console.WriteLine(response.Content);
}
}
}
$purchase_event = array(
'appsflyer_id' => <APPS_FLYER_DEVICE_ID>,
'idfa' => <IDFA>,
'eventCurrency' => <PURCHASE_CURRENCY>,
'ip' => <DEVICE_ID_ADDRESS>,
'eventTime' => date("Y-m-d H:i:s.000", time())
);
$purchase_event['eventName'] = 'af_purchase';
$purchase_event['eventValue'] = json_encode(array('af_revenue' => <PURCHASE_REVENUE>,
'af_price' => <PURCHASE_PRICE>,
'af_order_id' => <PURCHASE_ORDER_ID>,
'af_currency' => <PURCHASE_CURRENCY>,
'af_content_type' => <PURCHASE_TYPE>,
'af_quantity' => <PURCHASE_QUANTITY>,
'af_content' => <PRODUCT_NAME>,
'af_content_id' => <PRODUCT_ID>)
);
$data_string = json_encode($purchase_event);
$ch = curl_init('https://api2.appsflyer.com/inappevent/<YOUR_APP_ID>');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'authentication: <YOUR_APPS_FLYER_DEV_TOKEN>',
'Content-Length: ' . strlen($data_string))
);
$result = curl_exec($ch);
$curl = curl_init();
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 :
- Depuis l'appareil mobile en appelant l'API SDK AppsFlyer : Android, iOS
- Depuis la plate-forme AppsFlyer à l'aide de l'un des éléments suivants : API Pull, API Push, Exportation installation des données brutes.
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.45,123.456 - Exemples de valeurs invalides :
1,234.56,1,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