API de plataforma digital: servicio de audiencia instantánea
Nota:
Aviso alfa-beta
Este campo o característica forma parte de la funcionalidad actualmente en la fase Alfa o Beta. Por lo tanto, está sujeto a cambios.
Instant Audience Service es un método del lado servidor que usa una arquitectura de streaming para agregar grupos individuales o pequeños de usuarios a segmentos, a través de Digital Platform API. En lugar de agregar y enviar periódicamente grandes lotes de datos mediante el servicio batch segment, los usuarios de Instant Audience Service se asocian a segmentos casi en tiempo real. Nuestro acuerdo de nivel de servicio de destino para agregar usuarios a segmentos con este servicio es de 2 minutos. Esto resulta útil si tiene requisitos de remodelación de audiencia en tiempo real.
Configuración del servicio
Si ya usa el servicio de segmento de Batch, puede omitir esta parte y continuar con Autenticar. Si es un cliente nuevo y desea empezar a usar el Servicio de audiencia instantánea, deberá abrir una incidencia con y proporcionar la siguiente información:
- ¿Usa identificadores de usuario externos (es decir, usa mapUID para almacenar la asignación con Xandr)? Si usa los identificadores de usuario externos de otro miembro, incluya también los suyos
member_id. - ¿Necesita rellenar los segmentos que pertenecen a otros miembros? Si es así, proporcione el objeto asociado
member_ids. - ¿Cuándo desea que los segmentos expiren de forma predeterminada (por ejemplo, nunca expiren, expiren 60 días a partir de ahora, etcetera).)? Tenga en cuenta que si incluye EXPIRATION en el bloque seg, no se usará la expiración predeterminada.
- Las siguientes preguntas son para nuestro planeamiento interno de la capacidad:
- ¿Cuál es el número de identificadores de usuario únicos por publicación?
- ¿Cuál es el número de publicaciones esperadas al día?
- ¿Cuál es el número de segmentos únicos por publicación?
Autenticar
Consulte el servicio de autenticación para obtener información general sobre cómo realizar llamadas a la API de Xandr. Al igual que cualquier otro servicio, se autenticará en https://api.appnexus.com. Sin embargo, las llamadas posteriores se realizarán al Servicio de audiencia instantánea en https://streaming-data.appnexus.com.
Nota:
En la respuesta de autenticación, anote el token, ya que será necesario para las llamadas posteriores al Servicio de audiencia instantánea.
Respuesta de ejemplo del servicio de autenticación:
{
"response": {
"status": "OK",
"token": "hbapi:123456:9876abcd54321:nym2",
"dbg_info": {
...
}
}
}
El token devuelto en la respuesta debe incluirse en llamadas posteriores a Instant Audience Service en el encabezado de autorización o como parámetro de access_token cadena de consulta, como se muestra en los ejemplos siguientes:
Encabezado Authorization
curl -X POST -H "Authorization: hbapi:123456:9876abcd54321:nym2" https://streaming-data.appnexus.com/rt-segment
Cadena de consulta
curl -X POST https://streaming-data.appnexus.com/rt-segment?access_token=hbapi:123456:9876abcd54321:nym2
Agregar o quitar usuarios de segmentos
Después de autenticarse, ya está listo para agregar o quitar un usuario de un segmento, a través de un archivo JSON.
Nota:
Asegúrese de esperar aproximadamente 20 minutos antes de intentar agregar usuarios a los segmentos recién creados (para permitir que estos segmentos se propaguen a todos los servidores). Como procedimiento recomendado, intente minimizar la creación de nuevos segmentos, vuelva a usar los segmentos existentes siempre que sea posible o use el segmento valuespara dividir aún más a los usuarios dentro de los segmentos existentes. Estas prácticas garantizarán que el usuario agregue o quite correctamente los segmentos hacia y desde. Para obtener más información sobre la creación de segmentosvalues, vea Segment Pixels: Advanced and Segment Targeting (Píxeles de segmento: destino avanzado y segmento) en la documentación de la interfaz de usuario.
En el ejemplo siguiente se muestra cómo asignar un usuario a dos segmentos. En este ejemplo, el miembro agrega el identificador de usuario 12345678900987654321 (es decir, un identificador de usuario Xandr) a los segmentos 10001 y 10002, estableciendo ambas asociaciones con el valor = 1 y expirando en 1440 minutos.
Ejemplo sobre cómo asignar un usuario a dos segmentos
Llamada api
curl -X POST-H "Authorization: hbapi:123456:9876abcd54321:nym2"-d @json/segment.json "https://streaming-data.appnexus.com/rt-segment"
Carga de JSON
{
"rt_segment":
[
{
"user_id":"12345678900987654321",
"seg_block":[
{
"seg_id":10001,
"seg_code":null,"value":1,
"expiration":1440,
"member_id":null
},
{
"seg_id":10002,
"seg_code":null,
"value":1,
"expiration":1440,
"member_id":null
}
],
"domain":null
}
]
}
Respuesta
{
"response":{
"status":"OK",
"message":{
"users_in_request":1,
"segments_in_request":2
},
"warnings":[
]
}
}
Campos JSON
rt_segment array
| Campo | Tipo | Descripción |
|---|---|---|
user_id |
string | Este sería el Xandr user_id o un identificador basado en el dominio, como "AEBE52E7-03EE-455A-B3C4-E57283966239", como un ejemplo de un identificador de dispositivo.Obligatorio: Al menos uno. |
seg_block |
matriz | Matriz de bloques de segmentos para los segmentos que se van a asociar al usuario (consulte la estructura de bloques de segmentos a continuación). Obligatorio: Al menos uno. |
domain |
string | Tipo de identificador que se usa en la solicitud, como el identificador de usuario de Xandr (representado con null) o el identificador de dispositivo (idfa, sha1udid, md5udid, openudidy aaid).Nota: No use sha1mac, que quedó en desuso en 2019. |
seg_block array
| Campo | Tipo | Descripción |
|---|---|---|
seg_id |
Entero | Identificador del segmento Xandr. Obligatorio: Si no usa seg_code y member_id para identificar el segmento. |
seg_code |
string | Nombre definido por el usuario para el segmento. Nota: Puede incluir SEG_CODE y member_id o SEG_ID, pero no ambos.Obligatorio: Si no usa seg_ID para identificar el segmento. |
value |
Entero | Valor numérico que desea asignar a un segmento. |
expiration |
Entero | Duración de la asociación de segmento de usuario en minutos, a partir de cuando la leemos. Un valor de 0 significa que el segmento nunca expirará; -1 significa que el usuario se quitará de este segmento. |
member_id |
Entero | Identificador de miembro del propietario del segmento para el seg_block. Obligatorio: Si usa seg_code. |
Response
| Campo | Tipo | Descripción |
|---|---|---|
status |
string | Describe si el add/remove se realizó o produjo un error. |
users_in_request |
Entero | Número de usuarios leídos en la solicitud. Nota: Esto simplemente mostrará el número de usuarios detectados inicialmente en la solicitud, independientemente de si son válidos. |
segments_in_request |
Entero | Número de segmentos leídos en la solicitud. Nota: Esto simplemente mostrará el número de segmentos detectados inicialmente en la solicitud, independientemente de si son válidos en nuestro sistema y sin tener en cuenta a qué usuarios están asociados en la llamada. |
Escenarios adicionales POST
Uso del identificador de dispositivo (IDFA)
Llamada a la API REST (IDFA)
curl -X POST-H "Authorization: hbapi:123456:9876abcd54321:nym2"-d @json/segment.json "https://streaming-data.appnexus.com/rt-segment"
Carga json (IDFA)
{
"rt_segment":[
{
"user_id":"1ba98a6c-d1a5-49ef-ad1c-2d9230ebcd13",
"seg_block":[
{
"seg_id":12,
"seg_code":null,
"value":1,
"expiration":1440,
"member_id":null
},
{
"seg_id":23784,
"seg_code":null,
"value":1,
"expiration":0,
"member_id":null
}
],
"domain":"idfa"
}
]
}
Respuesta (IDFA)
{
"response":{
"status":"OK",
"message":{
"users_in_request":1,
"segments_in_request":2
},
"warnings":
[
]
}
Uso de códigos para otros miembros
Llamada a la API REST
curl -X POST-H "Authorization: hbapi:123456:9876abcd54321:nym2"-d @json/segment.json "https://streaming-data.appnexus.com/rt-segment"
Códigos de carga JSON para otros miembros
{
"rt_segment":[
{
"user_id":"12345678900987654321",
"seg_block":[{"seg_code":"abcd",
"value":1,
"expiration":1440,
"member_id":1661
},
{
"seg_code":"zywx",
"value":1,
"expiration":1440,
"member_id":1262
}
],
- "domain":null
}
]
}
Códigos de respuesta para otros miembros
{
"response":{
"status":"OK",
“users_in_request”:1,
"segments_in_request":2
}
}
Límites del servicio
Nota:
Los límites del servicio pueden cambiar durante las pruebas alfa y beta de este servicio.
Para cumplir con un máximo de dos minutos de tiempo de activación, el Servicio de audiencia instantánea tiene actualmente los siguientes límites:
| Tipo de límite | Descripción |
|---|---|
| Tasa de llamadas | Hasta 100 POST llamadas por segundo (por miembro) y hasta 1000 GET llamadas por segundo (por miembro). Si supera este límite de velocidad, se devolverá el siguiente mensaje: "Se ha superado el límite de velocidad. Ha superado el límite de solicitudes de 1000 lecturas por 1 segundo para procesar rt-segment-process, esperar e intentarlo de nuevo o ponerse en contacto con Xandr para obtener límites más altos". |
| Objetos | - Hasta 1000 usuarios por segundo. - Hasta 100 segmentos por usuario por llamada. |
| Tamaño de carga | La carga json no debe superar los 1 MB. |
Ejemplos de escenarios de error
Agregar o quitar más de 1000 usuarios en una solicitud
Llamada api para agregar o quitar más de 1000 usuarios en una solicitud
curl -X POST-H "Authorization: hbapi:123456:9876abcd54321:nym2"-d @json/1002_users.json "https://streaming-data.appnexus.com/rt-segment"
Carga json para 1000 usuarios en una solicitud
{
"rt_segment":[
{
"user_id":"12345678900987654321",
"seg_block":[
{
"seg_id":10001,
"seg_code":null,
"value":1,
"expiration":1440,
"member_id":null
},
{
"seg_id":10002,
"seg_code":null,
"value":1,
"expiration":1440,
"member_id":null
}
],"domain":"domain"
},
#... assume there are additional 1000 users inthisarray(1002in total)
]
}
Respuesta para 1000 usuarios en una solicitud
{
"response":{
"status":"OK",
"message":{
"users_in_request":1000,
"segments_in_request":2000
},
"warnings":[
{
"message":"Too many user_ids in request.",
"entity":{
"user_id":"23456789009876543211",
"seg_block":[
{
"seg_id":10001,
"seg_code":null,
"value":1,
"expiration":1440,
"member_id":null
},
{
"seg_id":10002,
"seg_code":null,
"value":1,
"expiration":1440,
"member_id":null
}
]
}
},
#... similar error will be sent for each user over 1000
]
}
}
seg_id o seg_code y member_id no se proporcionan
Carga JSON (seg_id/seg_code y member_id escenario de error)
{
"rt_segment": [
{
"user_id":"1",
"seg_block":
[
{
"seg_id":null,
"seg_code":"abc",
"value":1,
"expiration":1,
"member_id":null
}
]
}
]
}
Respuesta (seg_id/seg_code y member_id escenario de error)
{
"status":"OK",
"message":{
"users_in_request":0,
"segments_in_request":0},
"warnings":[
{
"message":"'seg_id' or 'seg_code' and 'member_id' are required",
"entity":{
"seg_code":"abc",
"value":1,
"expiration":1
}
},
{
"message":"No valid segments for user_id: 1.",
"entity":{
"user_id":"1",
"seg_block":[
{
"seg_code":"abc",
"value":1,
"expiration":1
}
]
}
},
{
"message":"No valid rt_segment in request.",
"entity":{
"rt_segment":[
{
"user_id":"1",
"seg_block":[
{
"seg_code":"abc",
"value":1,"expiration":1
}
]
}
]
}
}
]
}
seg_block no proporcionado
Carga json (seg_block escenario de error)
{
"rt_segment":[
{
"user_id":"asdf"
}
],
"domain":"domain"
}
Respuesta (seg_block escenario de error)
{
"status":"OK",
"message":{
"users_in_request":0,
"segments_in_request":0
},
"warnings":[
{
"message":"'seg_block' is required",
"entity":{
"user_id":"asdf"
}
},
{
"message":"No valid rt_segment in request.",
"entity":{
"rt_segment":[
{
"user_id":"asdf"
}
]
}
}
]
}
user_id está vacío
Carga json (user_id escenario de error)
{
"rt_segment":[
{
"seg_block":[
{
"seg_id":1,
"seg_code":null,
"value":1,
"expiration":1,
"member_id":null
}
]
}
],
"domain":"domain"
}
Respuesta (user_id escenario de error)
{
"status":"OK",
"message":{
"users_in_request":0,
"segments_in_request":0
},
"warnings":[
{
"message":"'user_id' is required and cannot be empty",
"entity":{
"seg_block":[
{
"seg_id":1,
"seg_code":null,
"value":1,
"expiration":1
}
]
}
},
{
"message":"No valid rt_segment in request.",
"entity":{
"rt_segment":[
{
"seg_block":[
{
"seg_id":1,
"seg_code":null,
"value":1,
"expiration":1
}
]
}
]
}
}
]
}