Data Clean Room - Travailler avec les sources

Les données contenues dans les sources doivent se conformer aux points suivants :

• Date et heure :
  • Format : aaaa-MMM-jj hh:mm:ss (ex : 2023-AVR-18 15:30:35)
  • Fuseau horaire : UTC
• Nombres : 2 chiffres maxi après la virgule
• Longueur de la chaîne : 256 caractères maximum
• Restrictions liées aux caractères :
  • Pour les noms de champs (en-têtes de colonnes) : aucun espace ni caractère spécial
  • Toutes les autres données : aucune restriction (tous les caractères sont valides)

En plus des données partagées en vue d'être traitées, les tableaux sources dans BigQuery ou Snowflake doivent inclure 2 autres colonnes, soit une pour la date et une pour la version :

• Date :
  • En-tête de colonne : dt
  • Type de colonne : date
  • Format des données : aaaa-mm-jj (ex : 2023-04-18)
  • Colonne supplémentaire : les tableaux BigQuery doivent être séparés par cette colonne.
• Version :
  • En-tête de colonne : v
  • Type de colonne : chaîne
  • Format des données : nombre (ex : 1, 2, 3, 10)
  • Important ! La nouvelle version d'un rapport est déclenchée à chaque fois que la DCR détecte une nouvelle valeur dans cette colonne. Pour garantir que votre rapport est bien complet, pensez à alimenter le tableau source avec un ensemble complet de données à chaque fois que la valeur de la colonne est modifiée.

Les fichiers sources stockés sur Amazon S3 ou GCS doivent suivre ces normes en matière de nom de fichier et de format :

• Le nom du fichier doit être conforme à la nomenclature utilisée dans la DCR ( ).
• Format CSV ou GZIP
  • Le fichier fondamental de la compression GZIP doit être un fichier CSV.
• Nombre de fichiers sources de données par dossier de données :
  • CSV : 1 maxi
  • GZIP : 1 fichier maxi en une seule partie. Les fichiers GZIP en plusieurs parties sont pris en charge lorsqu'ils sont nommés : nom_fichier_part01.gzip, nom_fichier_part02.gzip, etc.

1. Allez dans l'onglet Sources de la Data Clean Room.
2. Cliquez sur le bouton + Nouvelle source.
   Une page Nouvelle source s'ouvre.
3. Saisissez le nom de la source en haut à gauche de la page.
   • Vous pouvez choisir n'importe quel nom pourvu qu'il vous aide à identifier la source sur la plateforme DCR. Il ne doit pas forcément correspondre au nom du fichier.
   • Important ! Veillez à ce que le nom de la source ne soit pas utilisé pour une autre source sur votre compte, ou vous ne pourrez pas enregistrer la source.
   • Obligations pour le nom de la source :
     • Longueur : 2-80 caractères
     • Caractères valides :
       • lettres (A-Z, a-z)
       • les chiffres (0-9) ne peuvent pas être le premier caractère d'un nom ; 
     • Caractères non valides :
       • espaces
       • tous les autres symboles ou caractères spéciaux

Pour définir l'emplacement de la source :

1. Sélectionnez la connexion où la source sera (ou a été) créée.
   • Si aucune connexion n'a été définie dans votre compte, une boîte de dialogue Nouvelle connexion s'ouvre et vous invite à en créer une. Suivez ces instructions pour la créer.
   • Si vous avez déjà des connexions mais que vous souhaitez en utiliser une nouvelle, cliquez sur le bouton  pour ouvrir la boîte de dialogue Nouvelle connexion. Suivez ces instructions pour la créer.
2. Suivez les instructions ci-dessous en fonction de là où se trouvent les données de votre source.

Emplacements des sources dans BigQuery

Pour terminer la définition de l'emplacement de la source pour les sources BigQuery :

1. Sélectionnez l'ensemble de données où se trouve le tableau source.
2. Sélectionnez le tableau où se trouvent les données sources.

Les listes où vous sélectionnez ces éléments contiennent les ensembles de données et les tableaux disponibles dans le projet BigQuery que vous avez défini en créant la connexion.

Emplacements de la source dans Snowflake

Pour terminer la définition de l'emplacement de la source pour les sources Snowflake :

1. Sélectionnez le partage qui contient les données sources.
2. Sélectionnez le schéma où se trouve le tableau source.
3. Sélectionnez le tableau où se trouvent les données sources.

Les listes où vous sélectionnez ces éléments contiennent les partages, schémas et tableaux disponibles dans le projet Snowflake que vous avez défini en créant la connexion.

Emplacements des sources dans les compartiments de stockage sur le cloud

Les emplacements des sources dans Amazon S3 ou GCS correspondent à l'espace de stockage sur le cloud défini dans la connexion, ainsi que du chemin d'accès au dossier racine où la DCR lit le fichier source à chaque mise à jour. 

Une fois que vous avez spécifié la connexion, AppsFlyer peut générer automatiquement le chemin du dossier racine lors de la création de la source.

• Autorisez AppsFlyer à générer les dossiers facilite le processus. Cependant, vous pouvez choisir de les créer manuellement, en suivant ces instructions.

Si AppsFlyer génère les dossiers, la seule information supplémentaire requise est le nom que vous souhaitez donner au dossier source (le dossier de premier niveau où vous mettez à jour la source à chaque fois que vous l'utilisez pour éditer une nouvelle version de rapport.) Vous pouvez également indiquer si vous souhaitez que le dossier source soit créé dans un dossier parent - souvent nommé input.

Pour terminer la définition de l'emplacement de la source dans un compartiment sur le cloud, saisissez le nom du dossier source.

• Par défaut, le nom du dossier source affiché :
  • Se base sur le nom que vous avez donné à la source. Vous pouvez modifier le nom du dossier à condition qu'il soit suive la nomenclature de la DCR.
  • Indique qu'il sera généré dans un dossier parent nommé input. Ce dossier sert de dossier parent pour toutes les sources que vous importez dans le DCR.
    • Le dossier input n'est pas obligatoire et vous pouvez le supprimer, ou le nommer différemment (tant que vous suivez la nomenclature de la DCR.
    • Bien que ce dossier ne soit pas obligatoire, l'existence d'un dossier input (ou d'un dossier équivalent avec un nom différent) est souvent conseillé. Il est aussi fortement recommandé d'utiliser le même espace de stockage sur le cloud pour importer les fichiers de données (input) et recevoir des rapports (output).

Pour toutes les sources que vous partagez avec la DCR en vue d'être traitées, AppsFlyer doit savoir comment chaque champ de données doit être utilisé pour créer les rapports. Définir la structure de la source se fait comme suit :

• Chargement des champs source
• Classement de chaque champ (colonne) dans l'une des catégories suivantes :
  • Identifiant : champ qui identifie un utilisateur unique de l'application (ex. CUID, ID AppsFlyer, etc.).
    • La mission principale des ID dans une DCR est de relier les sources de données afin que les données de niveau utilisateur correspondantes puissent être utilisées.
  • Dimension : attribut permettant de classer les utilisateurs de l'application (ex. géographie, date d'installation, campagne, etc.)
  • Métrique : les données numériques que vous avez collectées au sujet d'un utilisateur d'app (ex. revenu, nombre d'ouvertures de l'appl, LTV, etc.)
    • Un champ de données défini comme étant une métrique ne peut contenir que des valeurs numériques.

Chargement des champs source

Chargez les champs source en suivant les instructions ci-dessous :

Sources de l'entrepôt de données

Pour charger les champs depuis une source située dans un entrepôt de données (BigQuery ou Snowflake), cliquez sur le bouton  .

Sources de compartiment de stockage sur le cloud

Pour charger des champs à partir d'une source située dans un compartiment de stockage sur le cloud (Amazon S3 ou GCS), vous devez importer un fichier source type.

Pour définir la structure de la source : 

• Vous pouvez importer une version type de la source depuis un fichier local.
  • Si vous sélectionnez cette option, AppsFlyer créera toujours le chemin du dossier source automatiquement.

                                                                - ou -

• Vous pouvez importer une version type du fichier source directement depuis sa connexion.
  • Si vous définissez cette option, vous devrez choisir entre :
    • Permettre à AppsFlyer de créer automatiquement la structure du dossier source, OU
    • Créer manuellement la structure du dossier source

Pour importer le fichier source de votre modèle, suivez les instructions dans l'onglet correspondant :

Classer les champs par catégorie

Après avoir importé les champs, AppsFlyer analyse le fichier, puis la liste de tous les champs de données (colonnes) s'affiche dans les Champs disponibles.

Pour classer les champs par catégorie :

1. Sélectionnez un ou plusieurs champs dans la liste Champs disponibles sur la gauche, puis utilisez les boutons au milieu de l'écran pour les mettre dans la catégorie identifiant, dimension ou métrique.
   • Une fois que vous avez classé un champ dans une catégorie, il s'affiche dans la liste de la catégorie correspondante, à droite de l'écran.
   • Vous pouvez utiliser la barre de recherche pour localiser les champs dans les listes.
   • Pour supprimer un champ d'une catégorie où il a été classé, sélectionnez-le dans la liste de la catégorie en question et utilisez le bouton Supprimer pour qu'il retourne dans la liste Champs disponibles.
2. Répétez l'opération jusqu'à ce qu'au classement de tous les champs que vous souhaitez inclure dans les rapports DCR.
   • Il n'est pas nécessaire de classer chaque champ dans la liste Champs disponibles. Toutefois, un champ doit forcément être catégorisé pour pouvoir être utilisé dans un rapport.
3. Si vous modifiez la source avant d'enregistrer la source, mais que vous souhaitez utiliser les champs des données source modifiées, cliquez sur le lien Charger à nouveau les champs, en bas de la liste Champs disponibles.
   • Notez qu'en chargeant à nouveau une source vous écraserez les noms des champs dans la liste des champs disponibles. Tous les champs précédemment catégorisés resteront dans les listes Identifiant, Dimension, ou Métrique.
   • Si un champ déjà catégorisé n'est pas inclus dans les données source à nouveau chargées, il s'affichera toujours dans la liste de sa catégorie, mais il sera marqué d'une icône d'erreur.

1. [Facultatif] Cliquez sur pour vérifier les erreurs de format ou de validité des champs source.
2. Cliquez sur Enregistrer pour enregistrer la source.

   La source est créée et un message de confirmation s'affiche.

   • Si vous avez importé la source depuis un fichier local, l'enregistrement de la source déclenche la création automatique de la structure du dossier, et le message de confirmation qui s'affiche contient un lien vers le dossier source.

   La nouvelle source apparaît dans la liste de toutes les sources existantes dans l'onglet Sources de la Data Clean Room.

La structure des sous-dossiers est la suivante :

• Dans le dossier source --> 1 sous-dossier pour chaque date ("dossier date")
  • Format : dt=yyyy-mm-dd/
  • Exemple : dt=2022-12-15/
• Dans chaque dossier de date --> 1 sous-dossier pour chaque version sur cette date ("dossier version")
  • Format : v=n/
  • Exemple : v=1/
  • Remarque : Le dossier version est requis même si vous n'importez le fichier qu'une fois par jour.
• Dans chaque dossier de version --> 1 sous-dossier pour indiquer l'emplacement des données ("folder données")
  • Format : data/
  • Le dossier données correspond à l'emplacement où le fichier source est importé.

Dans la plupart des cas, vous utilisez des appels d'API ou d'autres méthodes programmatiques pour créer automatiquement les dossiers date/version/données à chaque fois que le fichier source de données est importé. Pour plus d'informations, consultez la section API de votre service cloud : AWS, GCS.

Une fois que l'importation d'un fichier source dans le dossier de données est terminé, un fichier vide nommé _SUCCESS doit être importé dans le dossier version. Cette action signale à AppsFlyer qu'un nouveau fichier à traiter est disponible. Dans la plupart des cas, vous utilisez un script API pour générer et importer automatiquement ce fichier.

Important ! Le fichier _SUCCESS doit être importé dans le dossier version, en dehors du dossier données.

Le nom du fichier _SUCCESS :

• Doit être écrit tout en MAJUSCULE
• Doit être précédé d'un tiret du bas (_)
• Ne doit pas avoir d'extension de fichier

Pour les fichiers GZIP en plusieurs parties :

• Un seul fichier _SUCCESS doit être importé pour toutes les parties du fichier.
• Le fichier _SUCCESS ne doit être importé qu'une fois que toutes les parties du fichier ont été importées.

Après avoir importé des fichiers sources pendant deux jours (et créé par programme les dossiers date/version/données et les fichiers _SUCCESS), la structure de votre compartiment/dossier doit être celle-ci :

Pour modifier le nom de la source :

1. Allez dans l'onglet Sources de la Data Clean Room.
2. Dans la liste des sources, survolez la ligne de la source à modifier.
3. Cliquez sur le bouton d'édition à droite de la ligne.
4. Sur la page Modifier la source, modifiez le nom de la source.
5. Cliquez sur le bouton Enregistrer pour enregistrer la source avec le nouveau nom, ou sur Annuler  si vous souhaitez annuler vos modifications.

Pour modifier la structure de la source :

1. Allez dans l'onglet Sources de la Data Clean Room.
2. Dans la liste des sources, survolez la ligne de la source à modifier.
3. Cliquez sur le bouton d'édition à droite de la ligne.
4. Sur la page Modifier la source, les champs précédemment classés dans la catégorie identifiant, dimension ou métrique, s'affichent dans la nouvelle catégorie à droite de l'écran.
5. Vous pouvez déplacer un champ précédemment classé dans une nouvelle catégorie sans avoir à charger à nouveau les champs du fichier source. Pour ce faire :
   1. Tout d'abord, sélectionnez-le dans la liste de la catégorie en question et utilisez le bouton Supprimer pour qu'il retourne dans la liste Champs disponibles.
   2. Ensuite, sélectionnez-le dans la liste Champs disponibles et utilisez les boutons au milieu de l'écran pour le classer dans la catégorie identifiant, dimension ou métrique.
6. Pour travailler avec des rubriques du fichier source qui n'ont pas encore été catégorisées, il faut les charger à nouveau depuis l'emplacement de la source ou un fichier local. Accédez à cette action en cliquant sur le lien Charger à nouveau les champs au bas de la liste Champs disponibles.
7. AppsFlyer analyse le fichier, puis la liste de tous les champs de données (colonnes) qui n'ont pas encore été classés par catégorie s'affiche dans les Champs disponibles.
   • Les champs précédemment classés dans la catégorie identifiant, dimension ou métrique, s'affichent toujours dans la bonne catégorie à droite de l'écran.
   • Si un champ déjà catégorisé n'est pas inclus dans le fichier de la source à nouveau chargée, il s'affichera toujours dans la bonne catégorie, mais il sera marqué d'une icône d'erreur.
8. Sélectionnez un ou plusieurs champs dans la liste Champs disponibles sur la gauche, puis utilisez les boutons au milieu de l'écran pour les mettre dans la catégorie identifiant, dimension ou métrique.
9. Une fois que vous avez effectué toutes les modifications nécessaires, cliquez sur le bouton Enregistrer pour enregistrer la source avec la structure mise à jour, ou choisissez Annuler pour annuler vos modifications.

1. Allez dans l'onglet Sources de la Data Clean Room.
2. Dans la liste des sources, survolez la ligne de la source à supprimer.
3. Cliquez sur le bouton de suppression à droite de la ligne.
4. Dans la boîte de dialogue, confirmez la suppression de la source.
   • Vous ne pouvez pas supprimer une source qui est utilisée par un rapport. Si vous le faites, un message liste les rapports qui utilisent la source. Pour supprimer la source, vous pouvez au choix :
     • Supprimer les rapports qui l'utilisent, ou bien
     • Supprimer les champs sources des définitions de rapports qui l'utilisent.

En général, il est plus facile d'autoriser AppsFlyer à générer automatiquement la structure d'un dossier lors de la création de la source. Toutefois, si vous souhaitez créer ces dossiers manuellement, vous pouvez procéder comme suit.

Créer un dossier clé DCR

Pour garantir une sécurité maximale, le premier dossier situé dans le compartiment (le dossier «DCR key») doit porter le nom de la clé DCR composée de 8 caractères alphanumériques et attribuée à votre compte (ex. 01bcc5fb). Notez que ce mot de passe est différent de tout autre mot de passe ou clé associé à votre compte AppsFlyer.

Le dossier de la clé DCR est généralement créé manuellement via l'interface du service cloud que vous avez choisi.

Pour obtenir la clé DCR de votre compte, cliquez sur le bouton Clé DCR en haut de la page principale DCR.

Après avoir créé le dossier de la clé DCR, la structure de votre compartiment/dossier sera celle-ci :

Dossier d'entrée de premier niveau

Bien que cela ne soit pas obligatoire, le mieux consiste à créer un dossier d'entrée de premier niveau directement dans le dossier de la clé DCR. Ce dossier sera dédié aux fichiers que vous importez dans la DCR.

Le dossier d'entrée de premier niveau est généralement créé manuellement via l'interface du service cloud que vous avez choisi.

• Nous vous recommandons cette pratique si vous utilisez le même espace de stockage sur le cloud pour importer les fichiers de données (input) et recevoir des rapports (output).
• Vous pouvez donner n'importe quel nom au dossier, à condition qu'il soit suive la nomenclature de la DCR. Pour faciliter son identification, il est généralement nommé input/.

Après avoir créé le dossier d'entrée de premier niveau, la structure de votre compartiment/dossier sera celle-ci :

Dossier de second niveau pour chaque source de données

Vous pouvez régulièrement importer différents fichiers de sources de données vers la DCR pour qu'elles soient traitées. Chacune de ces sources de données doit se voir attribuer un dossier distinct («dossier source de données»).

Par exemple, si vous prévoyez d'envoyer chaque jour deux fichiers à la DCR pour traitement : BI-data.csv et CRM-data.gzip, vous devez attribuer un dossier à chacune de ces sources de données. Vous pouvez choisir d'appeler ces dossiers BI-data/ et CRM-data/.

Les dossiers de source de données sont généralement créés manuellement via l'interface du service cloud que vous avez choisi.

Après avoir créé 2 dossiers de source de données, la structure de votre compartiment/dossier sera celle-ci :

Dans chaque dossier de source de données, des sous-dossiers classés par date et par version doivent être créés à chaque mise à jour de la source.