API de plataforma digital: formato de archivo AVRO de BSS
En este documento se explica cómo preparar los archivos de audiencia mediante el formato de archivo AVRO e incorporar los datos a la plataforma. AVRO es necesario para cargar audiencias que contengan identificadores extendidos y identificadores proporcionados por el publicador, y el formato de archivo BSS heredado no admite los tipos de identificador de usuario más recientes.
- Los segmentos se pueden crear a través del servicio segment.
- Los archivos de audiencia se pueden cargar en segmentos a través del servicio de segmentos de Batch.
Procedimientos recomendados
- Tamaño de archivo recomendado: 100-300 mb por archivo
- Compresión de archivos recomendada: deflate
- Método de entrega recomendado: Carga pasiva de segmentos (póngase en contacto con el Administrador de cuentas para obtener acceso)
- Actualizar segmentos: en lugar de volver a enviar las pertenencias a la audiencia completa, solo puede cargar los cambios para los segmentos existentes. Esto reducirá el tamaño de los datos y la posibilidad de alcanzar los límites de carga diarios.
Información general sobre los pasos
- Descripción del registro de segmentos de usuario
- Instalación de la biblioteca de herramientas de AVRO
- Descarga del archivo de esquema Xandr AVRO
- Generación del archivo de audiencia de AVRO
Registro de segmentos de usuario
Un registro de usuario tiene dos elementos de nivel superior:
- Id. de usuario (uid)
- matriz de segmentos
Tipos de identificador de usuario
Solo se puede cargar un tipo de identificador por registro uid (por ejemplo, id. de usuario de Xandr, IFA, id. de dispositivo, eid).
En esta sección, busque los distintos tipos de identificador de usuario admitidos junto con sus descripciones y un ejemplo de biblioteca de Java y biblioteca de Python para cada uno.
AppNexus/Xandr User ID (ANID)
Id. de Xandr, también conocido como user_id_64.
Ejemplo de biblioteca de Java:
{"uid":
{"long":12345},
"segments":
[{"id":123,
"code":"",
"member_id":0,
"expiration":0,
"timestamp":0,
"value":0}]}
Ejemplo de biblioteca de Python:
{'uid': 64, 'segments': [seg1]}
Device ID
Utilidad similar a ifa (identificador de publicidad). Indica el tipo de dispositivo móvil que se va a incorporar. El device_id registro consta de dos campos:
- domain (enum): los valores posibles son idfa, sha1udid, md5udid, openudid, aaid, windowsadid, rida, tifa, vida y lgudid.
- id (cadena)
Ejemplo de biblioteca de 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}]}
Ejemplo de biblioteca de Python:
{'uid': {'id': 'qweqeqweq', 'domain': 'idfa'}, 'segments': [seg1]}
Extended ID's(eid) or Publisher-provided ID's(PPID)
Id. extendido: indica el tipo de identificador universal o identificador de publicador que se va a incorporar. El registro eid consta de dos campos:
- source (cadena): origen del identificador. Los valores permitidos son orígenes definidos por miembros con permiso.
- id (cadena): id. del publicador o del sector.
En la actualidad, estos son los dos únicos disponibles para la incorporación de público.
Ejemplo de biblioteca de Java:
{"uid":
{"eid":
{"source":"liveramp.com",
"id":"123123123"}},
"segments":
[{"id":123,
"code":"",
"member_id":0,
"expiration":0,
"timestamp":0,
"value":0}]}
Ejemplo de biblioteca de Python:
{'uid': {'id': 'qweqeqweq', 'source': 'liveramp.com'}, 'segments': [seg1]}
External ID
Identificador externo: indica el identificador definido por el miembro que se va a incorporar. El external_id registro consta de dos campos:
- member_id (int): identificador de miembro del miembro propietario de
external_id. - id (cadena): valor correspondiente de
member_id.
Ejemplo de biblioteca de Java:
{"uid":
{"external_id":
{"id":"clientid1",
"member_id":958}},
"segments":
[{"id":123,
"code":"",
"member_id":0,
"expiration":0,
"timestamp":0,
"value":0}]}
Ejemplo de biblioteca de Python:
{'uid': {'id': 'extid1', 'member_id': 914}, 'segments': [seg1]}
Identifier for Advertising (or IFA)
Identificador de publicidad: indica el tipo de dispositivo que se va a incorporar. El registro ifa consta de dos campos:
- tipo (cadena): tipo de identificador.
- id (cadena): id. de IFA, que representa el IFA en formato UUID.
Consulte Device Extension Object (Objeto de extensión de dispositivo) para ver los tipos ifa admitidos.
Ejemplo de biblioteca de Java:
{"uid":
{"ifa":
{"id":"99136473264876328",
"type":"atif"}},
"segments":
[{"id":123,
"code":"",
"member_id":0,
"expiration":0,
"timestamp":0,
"value":0}]}
Ejemplo de biblioteca de Python:
{'uid': {'id': 'qweqeqweq', 'type': 'atif'}, 'segments': [seg1]}
Objeto Segments
Puede cargar en varios segmentos dentro del mismo registro uid creando una matriz de objetos de segmento.
| Archivo | Tipo | Descripción |
|---|---|---|
code |
string | Código de segmento Xandr. |
expiration |
Entero | Expiración del segmento en minutos. Establézcalo en: - 0 expiración máxima (180 días). - -1 para la eliminación de segmentos. - -2 para la expiración predeterminada del miembro. |
id |
Entero | Id. de segmento de Xandr |
member_id |
Entero | Id. de miembro del segmento. Necesario cuando se especifica código |
timestamp |
largo | Segmentar el tiempo de activación en segundos desde la época. Especifica cuándo se convierte el segmento en "dinámico". Establezca en 0 para activar el segmento inmediatamente. |
value |
Entero | Valor de segmento |
Instalación de la biblioteca de herramientas de AVRO
- Biblioteca de Java
curl -o http://archive.apache.org/dist/avro/avro-1.10.1/java/avro-tools-1.10.1.jar
- Biblioteca de Python
python3 -m pip install avro
Descarga del esquema de Xandr Avro
Puede descargar el esquema Xandr Avro desde aquí.
Generación del archivo de audiencia de AVRO
Consulte a continuación los ejemplos que usan las bibliotecas de Java y Python:
Ejemplo de Java
Create un archivo de audiencia
{"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}]}
Conversión del archivo de audiencia en AVRO
Ejecute el siguiente comando:
java -jar avro-tools-1.10.1.jar fromjson --codec deflate --schema-file xandr_schema.avsc sample.json > sample.avro
Dónde
- xandr_schema.avsc = el archivo de esquema Xandr Avro proporcionado;
- sample.json = el archivo de audiencia;
- and sample.avro = archivo AVRO de salida
Ejemplo de Python
Nota:
Nuestros ejemplos son para la biblioteca avro de Python y no deben confundirse con la biblioteca de Fast Avro.
La biblioteca de Avro de Python no usa nombres de tipo de unión uid. En su lugar, determina el tipo uid por coincidencia completa de nombres de campo.
Ejemplo:
{'uid': {'id': 'qweqeqweq', 'domain': 'idfa'}, 'segments': […]}
- La biblioteca de Fast Avro usa sugerencias para especificar el tipo exacto de uid similar a la biblioteca de Java.
Ejemplo:
{'uid': ('external_id', {'id':'exitd1', 'member_id': 914}), 'segments': [{'expiration': 259200, 'id': 25815407}]}
- DataFileWriter.append() acepta un tipo de diccionario de Python (dict), no un JSON.
Creación de un archivo de audiencia de AVRO
Script de ejemplo mediante la biblioteca avro de Python:
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()