En bref : L'API de rapports des cohortes donne aux annonceurs un moyen pratique pour obtenir les données de cohorte. L'API permet d'intégrer les données de cohorte dans les BI et les systèmes d'automatisation marketing.
API de rapports des cohortes
L'API de rapports des cohortes permet d'obtenir les performances des campagnes de cohorte depuis la plateforme AppsFlyer. Elle fonctionne comme le tableau de bord des cohortes.
À l'attention des développeurs
- Dates : les dates ou périodes se réfèrent aux dates de lifetime (LTV), c'est-à-dire à la date d'attribution (conversion) de l'utilisateur et non celle de l'activité elle-même.
- Valeurs booléennes : doit être true ou false (sensible à la casse).
- Trafic d'agence transparent et non transparent : la source média du trafic issue d'une agence correspond toujours à l'agence et non à la source média d'origine. Pour l'instant, la version de cohorte UI de cohorte se comporte différemment.
- Application unique : l'API de Cohorte est une solution pour application unique. Elle contraste avec le tableau de bord de cohorte qui prend en charge plusieurs applications pour même appel.
- Actualisation des données : cf caractéristiques et limitations.
Mode d'emploi de l'API
Les sections contiennent les informations pour générer et utiliser l'API de Cohorte.
Faits relatifs à l'API de cohorte
| Présentation | L'appel de l'API se compose du chemin d'accès, d'en-têtes et d'un JSON contenant la demande de données. Les données sont renvoyées par défaut dans un fichier CSV. |
| Chemin |
|
| Paramètres du chemin d'accès (obligatoire) |
|
|
Paramètres de requête (facultatif) |
Les résultats sont renvoyés au format CSV ou JSON. La structure du fichier CSV est en tableau, tandis que celle du fichier JSON est conçue pour être enregistrée.
|
| Méthode HTTP | POST |
| Types de contenu acceptés | application/json |
| Autorisation |
|
| Limites dans le temps |
|
| Limitation de taux |
|
| Valeurs booléennes | Toujours en minuscules : true, false |
En-têtes de requête
|
Clé |
valeur | Obligatoire |
|---|---|---|
| Type de contenu | application/json |
Oui |
| Authorization | Porteur api_token_placeholder |
Oui |
| Accepter | application/json |
Oui |
Paramètres de filtrage et de regroupement
Utilisez les paramètres de filtrage suivants pour obtenir les données nécessaires.
|
Nom du paramètre |
Description | Obligatoire |
|---|---|---|
|
cohort _type |
Le type d'attribution de cohorte (conversion) est l'un des suivants :
|
Oui |
|
min_cohort_size |
La taille minimum de cohorte permet de réduire le nombre d'enregistrements renvoyés vec des cohortes qui ont peu d'utilisateurs. Cela signifie que le KPI des users aura une valeur égale ou supérieure à celle spécifiée.
|
Non |
|
de |
Seuil le plus bas de la période d'attribution LTV La date la plus ancienne prise en charge, 720 jours avant la date actuelle.
|
Oui |
|
to |
Limite maximum de la période d'attribution LTV
|
Oui |
|
granularité |
Granularité horaire pour les 72 heures précédentes en définissant
"granularity": "hour",
"from": "2021-12-01 14:00:00", "to": "2021-12-03 11:00:00",
|
Non |
|
partial_data |
Pour éviter les erreurs d'interprétation, la cohorte renvoie les données des jours complets. Les données des jours partiels peuvent cependant aussi être utiles. Le nombre de jours de cohorte complets pour une requête est calculé en soustrayant la date du jour de la date qui correspond à to.
Exemple : au 10 mai, le nombre de jours de cohorte complets pour les utilisateurs convertis entre le 1er et le 30 avril est de 10.
Remarque : les données partielles ne sont autorisées que lorsque le type d'agrégation est cumulatif. |
Non |
|
Filtres |
Filtrer les données et les jours de période renvoyés. Sélectionnez les filtres dans la liste des dimensions de filtre.
|
Non |
Utilisez les paramètres de regroupement suivants pour inclure des colonnes supplémentaires et diminuer la granularité de vos rapports.
|
Paramètre |
Valeurs | Obligatoire |
|---|---|---|
|
regroupements |
|
Oui |
Sélectionner et formater les KPI
- Le tableau énumère les KPI disponibles avec les fonctionnalités. Lorsque vous appelez un KPI, toutes ses fonctionnalités sont renvoyées.
- Les KPI suivants sont toujours renvoyés : utilisateurs, ecpi et coût.
- Sélectionnez un KPI supplémentaire par appel.
| Fonctions | ||||||
|---|---|---|---|---|---|---|
| Défaut / Facultatif | V (nom des dimensions) | Décompte | cvr (taux de conversion) | Taux | Total | Utilisateurs uniques |
| Nombre | Pourcentage | Pourcentage | Nombre | Nombre | ||
| Toujours | utilisateurs | Y | - | - | - | - |
| Toujours | eCPI | - | - | Y | - | - |
| Toujours | coût | - | - | - | Y | - |
| OPTIONNEL | "event_name"(4) |
Y | Y | - | Y (3) | Y |
| OPTIONNEL | revenus | Y | - | - | Y | - |
| OPTIONNEL | ROAS | - | - | Y | - | - |
| OPTIONNEL | roi | - | - | Y | - | - |
| OPTIONNEL | Sessions | Y | - | Y | - | Y(1) |
| OPTIONNEL | désinstallations (2) | Y | - | Y | - | - |
|
(1) Les sessions uniques se réinitialisent lorsque aggregation_type=on_day (2) Non disponible lorsque cohort_type=unified (3) La somme correspond au revenu total généré par l'événement. Dans le rapport, il est désigné par Attention : les noms d'évènements sont sensibles à la casse. |
||||||
|
Paramètre |
Valeurs | Paramètre obligatoire |
|---|---|---|
|
KPIs |
Sélectionnez un KPI parmi les KPI disponibles. À l'avenir, nous prévoyons d'autoriser la sélection de plusieurs KPI.
|
Oui |
Présentation des fonctionnalités du KPI
Les formats de paramètres des KPI P suivants définissent le format des KPI renvoyés.
|
Paramètre |
Valeurs | Obligatoire |
|---|---|---|
|
preferred_currency |
Devise du revenu de KPI
|
Non |
|
preferred_timezone |
Fuseau horaire des périodes de données
|
Non |
|
aggregation_type |
|
Oui |
|
per_user |
Divisez la fonction du KPI par le nombre d'utilisateurs de l'app. Ne s'applique qu'aux KPI concernés.
|
Non |
Liste des dimensions de regroupement et de filtrage
|
Nom de la dimension |
Valeurs des dimensions d'API |
Regroupements |
Filtres |
|---|---|---|---|
|
Publicité |
af_ad |
Y |
Y |
|
Identifiant de publicité |
af_ad_id |
Y |
Y |
|
Campagne |
C |
Y |
Y |
|
Identifiant de la campagne |
af_c_id |
Y |
Y |
|
Canal |
af_channel |
Y |
Y |
|
Source média |
PID |
Y |
Y |
|
Sous-paramètre 1 |
af_sub1 |
Y |
Y |
|
Mots-clés |
af_keywords |
Y |
Y |
|
agences |
af_prt |
Y |
Y |
|
Type de conversion (1) |
cohort_type |
Y |
Y |
|
ID site |
site_id |
Y |
Y |
|
Type de revenu (2) |
revenue_type |
x |
Y |
|
Type de touch attribué (3) |
attributed_touch_type |
Y |
Y |
|
Ensemble de publicités |
af_adset |
Y |
Y |
|
Identifiant de l'ensemble de publicités |
af_adset_id |
Y |
Y |
|
Pays |
geo |
Y |
Y |
|
Date (date d'installation/d'attribution/d'engagement pour le type de cohorte sélectionné) |
date |
Y |
x |
|
Période |
période
|
X |
Y |
|
Remarque : Options de dimensions : (1) Type de conversion :
(2) Type de revenu : clic, impression, TV, pre-installed
|
|||
Exemple en curl
Cet exemple contient un appel d'API complet.
curl -L -X POST 'https://hq1.appsflyer.com/api/cohorts/v1/data/app/<insert your app_id here>?format=<insert results format here>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <cohort_api_token_placeholder. Note the token has more than 700 characters.>' \
-H 'Accept: application/json' \
--data-raw '{
"cohort_type": "user_acquisition",
"min_cohort_size": 1,
"preferred_timezone": false,
"from": "2020-01-01",
"to": "2020-01-31",
"filters": {
"period": [
0,
1,
2,
10,
30,
60
],
"geo": [
"US",
"CN"
],
"pid": [
"Meta ads",
"googleadwords_int"
]
},
"preferred_currency": true,
"aggregation_type": "on_day",
"per_user": false,
"groupings": [
"pid",
"date"
],
"kpis": [
"sessions"
]
}'
Exemple Python
import http.client
import mimetypes
conn = http.client.HTTPSConnection("hq1.appsflyer.com")
payload = "{\r\n \"cohort_type\": \"user_acquisition\",\r\n \"min_cohort_size\": 1,\r\n \"preferred_timezone\": false,\r\n \"from\": \"2020-05-01\",\r\n \"to\": \"2020-05-10\",\r\n \"preferred_currency\": true,\r\n \"aggregation_type\": \"cumulative\",\r\n \"per_user\": false, \r\n \"groupings\": [\r\n \"pid\",\r\n \"date\"\r\n ],\r\n \"kpis\": [\r\n \"roas\"\r\n ]\r\n}"
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer [Enter token here]',
'Accept': 'application/json',
'Content-Type': 'application/json'
}
conn.request("POST", "/api/cohorts/v1/data/app/[My App ID here]?format=csv", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Exemples pratiques
Exemple 1 : rétention
Rétention des sources média (sessions) des utilisateurs qui ont installé l'application en janvier, aux jours 7, 14 et 28.
{
"per_user": false,
"groupings": [
"pid"
],
"filters": {
"period": [
7, 14, 28
]
},
"partial_data": false,
"aggregation_type": "on_day",
"min_cohort_size": 1,
"cohort_type": "user_acquisition",
"from": "2021-01-01",
"to": "2021-01-30",
"kpis": [
"sessions"
]
}Exemple 2 : achats de campagne
Revenu post-installation du jour 3 de cohorte par campagne
{
"per_user": false,
"groupings": [
"c"
],
"filters": {
"period": [
3
],
"c":[
"example_campaign_name"
]
},
"partial_data": false,
"aggregation_type": "cumulative",
"min_cohort_size": 1,
"cohort_type": "user_acquisition",
"from": "2021-01-01",
"to": "2021-01-30",
"kpis": [
"Checkout Start"
]
}Exemple 3 : Activité d'hier
Quelle activité ont effectué les utilisateurs convertis (installés, réengagés, réattribués) au cours d'une période de conversion donnée ?
Utiliser les données disponibles via Cohorte pour Data Locker. La période de conversion est limitée aux 360 jours précédents.
Informations supplémentaires
Codes de réponse et dépannage
|
Code de réponse |
Message |
Remarque |
|---|---|---|
| 200 | OK |
Données valides renvoyées |
| 200 | OK |
|
| 401 | Non autorisé |
|
| 404 | Pas de résultat |
|
| 422 | Entité non traitable |
Les raisons fréquentes pour ce code d'erreur sont les suivantes :
|
Structure du nom de fichier CSV
Le nom attribué à un fichier CSV est généré à partir de la requête d'API. La du fichier structure est détaillée dans le tableau suivant.
Exemple de nom de fichier CSV
cohort_aggregation_type_per_user_kpi_report_app_id_from_to_timezone_currency_hash.csv| Variable | Valeurs possibles |
|---|---|
| aggregation_type |
|
| per_user |
|
| KPI | Exemple : sessions |
| app_id | L'ID d'app appelée |
| from | from date : format aaaa-mm-jj |
| to | to date : format aaaa-mm-jj |
| Fuseau horaire | Fuseau horaire par défaut UTC |
| devise | Code devise par défaut USD |
| hachage |
Chaîne de hachage alphanumérique longueur=5 |
Utilisation des filtres pour les périodes
La période fait référence au jour suivant l'attribution, la période 0 correspondant au jour de l'attribution. Exemple, un utilisateur installe l'application au 1er janvier. C'est le jour de l'attribution. Un achat effectué au cours de la période 0 signifie qu'il a été effectué durant le 1er janvier. Un achat effectué à la période 3 signifie qu'il a été effectué le 4 janvier. De même, un utilisateur qui installe l'app le 11 janvier correspond à la période 0. Un achat effectué le 14 janvier correspond à la période 3.
Si la période couverte par votre rapport va du 1er au 11 janvier, les utilisateurs qui sont attribués (qui ont installé l'app) au cours de cette période sont compris dans le rapport. Aucune autre donnée n'est incluse.
- La valeur de la période peut être une ou plusieurs des nombres suivants compris entre 0 et 180. Par exemple 0, 1, 2, 30, 180.
- Si aucune période n'est spécifiée, les valeurs par défaut 0, 1, 2, etc jusqu'à 30, 60, 90 et 180 seront renvoyées.
Exemple de filtre de période
- Cet exemple contient les paramètres de la requête JSON, les données brutes et le fichier CSV résultant.
- La requête filters period de 0, 1, et 2 et le KPI sélectionné est revenue.
- Ainsi, les données renvoyées contiennent :
- Les mesures des utilisateurs, du coût et de l'ecpi qui sont systématiquement renvoyés
- Mesures des revenus consistant en la somme et le décompte pour chaque période, c'est-à-dire les périodes 0, 1 et 2.
Requête
{
"cohort_type": "user_acquisition",
"min_cohort_size": 1,
"preferred_timezone": false,
"from": "2019-12-01",
"to": "2020-01-01",
"filters": {
"period": [
0,
1,
2
]
},
"aggregation_type": "on_day",
"per_user": false,
"groupings": [
"pid"
],
"kpis": [
"revenue"
]
}
Données Brutes
Résultats
Mapping entre l'interface utilisateur et les paramètres de l'API
Les chiffres suivants matchent l'interface utilisateur d'analyse de Cohorte avec les paramètres de l'API. Les deux solutions - API et interface utilisateur - sont similaires mais pas complétement identiques.
La version API contient les options supplémentaires suivantes :
- Sélection de la devise
- Sélection du fuseau horaire
- Filtrage par période
Différence entre les types d'agrégation
Caractéristiques et limitations
| Caractéristique | Remarques |
|---|---|
| Accès du ad network |
Les partenaires de gestion de campagne peuvent utiliser l'API si l'annonceur leur en donne l'autorisation. |
| Autorisations de l'agence | Non |
| Transparence de l'agence | Non pris en charge |
| Fuseau horaire spécifique à l'app | Oui |
| Devise spécifique à l'app | Oui |
| Limitations de taille | Aucun |
| Limitation de taux |
Limite d'appels d'API : 60 appels par minute et par compte |
| Données organiques | Disponible |
| Données non organiques | Disponible |
| Limitation des données de coûts |
|
| Actualisation des données |
L'actualisation des données dépend de partial_data comme suit :
|
| Données historiques | Cohorte quotidienne : 2 ans |
| Accès utilisateur du compte | Le jeton d'autorisation est disponible pour les utilisateurs admin dans le tableau de bord. |
| Revenus publicitaires |
Pour les événements af_ad_revenue, la mesure des utilisateurs uniques n'est pas disponible lorsque le type d'agrégation est réglé sur "on day," pour les dates comprises entre le 5 octobre 2022 et le 16 février 2023. |
| Regroupements hebdomadaires et mensuels |
Le regroupement des dimensions hebdomadaires et mensuelles n'est pas disponible avec l'API de cohorte. Utilisez le tableau de bord de Cohorte. |
| API de cohorte |
|