API de plateforme numérique - Format de fichier BSS AVRO

Ce document explique comment préparer vos fichiers d’audience à l’aide du format de fichier AVRO et intégrer les données à la plateforme. AVRO est nécessaire pour charger des audiences contenant des ID étendus et des ID fournis par l’éditeur, et le format de fichier BSS hérité ne prend pas en charge les types d’ID utilisateur plus récents.

• Les segments peuvent être créés via le service segment.
• Les fichiers d’audience peuvent être chargés sur des segments via le service batch segment.

Meilleures pratiques

• Taille de fichier recommandée : 100-300 Mo par fichier
• Compression de fichier recommandée : deflate
• Méthode de remise recommandée : Chargement de segment passif (contactez votre gestionnaire de compte pour y accéder)
• Mise à jour des segments : au lieu d’envoyer à nouveau les appartenances d’audience complètes, vous pouvez charger uniquement les modifications pour les segments existants. Cela réduira la taille des données et les chances d’atteindre vos limites de chargement quotidiennes.

Vue d’ensemble des étapes

• Présentation de l’enregistrement User-segments
• Installer la bibliothèque d’outils AVRO
• Télécharger le fichier de schéma Xandr AVRO
• Générer votre fichier d’audience AVRO

Enregistrement des segments d’utilisateur

Un enregistrement utilisateur a deux éléments de niveau supérieur :

• ID d’utilisateur (uid)
• tableau de segments

Types d’ID utilisateur

Un seul type d’ID peut être chargé par enregistrement uid (par exemple, ID utilisateur Xandr, IFA, ID d’appareil, eid).

Dans cette section, recherchez les différents types d’ID utilisateur pris en charge, ainsi que leurs descriptions, ainsi qu’une bibliothèque Java et un exemple de bibliothèque Python pour chacun d’eux.

AppNexus/Xandr User ID (ANID)

ID Xandr, également appelé user_id_64.

Exemple de bibliothèque Java :

{"uid":
{"long":12345},
"segments":
[{"id":123,
"code":"",
"member_id":0,
"expiration":0,
"timestamp":0,
"value":0}]}

Exemple de bibliothèque Python :

{'uid': 64, 'segments': [seg1]}

Device ID

Utilitaire similaire à ifa (Identificateur pour la publicité). Il indique le type d’appareil mobile en cours d’intégration. L’enregistrement device_id se compose de deux champs :

• domain (enum) : les valeurs possibles sont idfa, sha1udid, md5udid, openudid, aaid, windowsadid, rida, tifa, vida et lgudid.
• id (chaîne)

Exemple de bibliothèque Java :

{"uid":
{"device_id":
{"id":"958cba26-f338-43f3-8bb0-ed821582daae",
"domain":"idfa"}},
"segments":
[{"id":123,
"code":"",
"member_id":0,
"expiration":0,
"timestamp":0,
"value":0}]}

Exemple de bibliothèque Python :

{'uid': {'id': 'qweqeqweq', 'domain': 'idfa'}, 'segments': [seg1]}

Extended ID's(eid) or Publisher-provided ID's(PPID)

ID étendu : indique le type d’ID universel ou d’ID d’éditeur en cours d’intégration. L’enregistrement eid se compose de deux champs :

• source (chaîne) : source de l’ID. Les valeurs autorisées sont des sources définies par les membres avec autorisation.
• id (chaîne) : ID du serveur de publication ou du secteur d’activité.

Aujourd’hui, il s’agit des deux seuls disponibles pour l’intégration du public.

Exemple de bibliothèque Java :

{"uid":
{"eid":
{"source":"liveramp.com",
"id":"123123123"}},
"segments":
[{"id":123,
"code":"",
"member_id":0,
"expiration":0,
"timestamp":0,
"value":0}]}

Exemple de bibliothèque Python :

{'uid': {'id': 'qweqeqweq', 'source': 'liveramp.com'}, 'segments': [seg1]}

External ID

ID externe : indique l’identificateur défini par le membre en cours d’intégration. L’enregistrement external_id se compose de deux champs :

• member_id (int) : ID de membre du membre propriétaire de external_id.
• id (chaîne) : valeur correspondante du member_id.

Exemple de bibliothèque Java :

{"uid":
{"external_id":
{"id":"clientid1",
"member_id":958}},
"segments":
[{"id":123,
"code":"",
"member_id":0,
"expiration":0,
"timestamp":0,
"value":0}]}

Exemple de bibliothèque Python :

{'uid': {'id': 'extid1', 'member_id': 914}, 'segments': [seg1]}

Identifier for Advertising (or IFA)

Identificateur de la publicité : indique le type d’appareil en cours d’intégration. L’enregistrement ifa se compose de deux champs :

• type (chaîne) : type d’ID.
• id (chaîne) : ID IFA, représentant l’IFA au format UUID.

Consultez Objet d’extension d’appareil pour les types ifa pris en charge

Exemple de bibliothèque Java :

{"uid":
{"ifa":
{"id":"99136473264876328",
"type":"atif"}},
"segments":
[{"id":123,
"code":"",
"member_id":0,
"expiration":0,
"timestamp":0,
"value":0}]}

Exemple de bibliothèque Python :

{'uid': {'id': 'qweqeqweq', 'type': 'atif'}, 'segments': [seg1]}

Objet Segments

Vous pouvez charger vers plusieurs segments dans le même enregistrement uid en créant un tableau d’objets segment.

Installation de la bibliothèque d’outils AVRO

• Bibliothèque Java

curl -o http://archive.apache.org/dist/avro/avro-1.10.1/java/avro-tools-1.10.1.jar

• Bibliothèque Python

python3 -m pip install avro

Télécharger le schéma Xandr Avro

Vous pouvez télécharger le schéma Xandr Avro ici.

Générer votre fichier d’audience AVRO

Consultez ci-dessous pour obtenir des exemples d’utilisation des bibliothèques Java et Python :

Exemple Java

Create un fichier d’audience

{"uid":{"long":12345},"segments":[{"id":123,"code":"","member_id":0,"expiration":0,"timestamp":0,"value":0}]}
{"uid":{"external_id":{"id":"clientid1","member_id":958}},"segments":[{"id":123,"code":"","member_id":0,"expiration":0,"timestamp":0,"value":0}]}
{"uid":{"ifa":{"id":"99136473264876328","type":"atif"}},"segments":[{"id":123,"code":"","member_id":0,"expiration":0,"timestamp":0,"value":0}]}
{"uid":{"device_id":{"id":"958cba26-f338-43f3-8bb0-ed821582daae","domain":"idfa"}},"segments":[{"id":123,"code":"","member_id":0,"expiration":0,"timestamp":0,"value":0}]}
{"uid":{"eid":{"source":"liveramp.com","id":"123123123"}},"segments":[{"id":123,"code":"","member_id":0,"expiration":0,"timestamp":0,"value":0}]}

Convertir le fichier d’audience en AVRO

Exécutez la commande suivante :

java -jar avro-tools-1.10.1.jar fromjson --codec deflate --schema-file xandr_schema.avsc sample.json > sample.avro  

Où

• xandr_schema.avsc = le fichier de schéma Xandr Avro fourni ;
• sample.json = votre fichier d’audience ;
• et sample.avro = fichier AVRO de sortie

Exemple Python

Création d’un fichier d’audience AVRO

Exemple de script utilisant la bibliothèque Python Avro :

import avro.schema
from avro.datafile import DataFileReader, DataFileWriter
from avro.io import DatumReader, DatumWriter
  
# the supplied xandr schema
schema = avro.schema.parse(open("xandr_schema.avsc", "rb").read())
  
# output avro file 
writer = DataFileWriter(open("sample.avro", "wb"), DatumWriter(), schema, codec=’deflate’)
   
# segments
seg1 = {'id': 1000, 'code': '', 'member_id': 0, 'expiration': 0, 'timestamp': 0, 'value': 0}
   
# anid
writer.append({'uid': 64, 'segments': [seg1]})
   
# external id
writer.append({'uid': {'id': 'exitd1', 'member_id': 914}, 'segments': [seg1]})
   
# idfa
writer.append({'uid': {'id': 'qweqeqweq', 'domain': 'idfa'}, 'segments': [seg1]})
   
# eid (or ppid)
writer.append({'uid': {'id': 'qweqeqweq', 'source': 'liveramp.com'}, 'segments': [seg1]})
writer.append({'uid': {'id': 'qweqeqweq', 'source': 'netid.de'}, 'segments': [seg1]})
   
writer.close()