API de plataforma digital: servicio de audiencia instantánea

El servicio de audiencia instantánea es un método del lado del servidor que usa una arquitectura de streaming para agregar grupos individuales o pequeños de usuarios a segmentos, a través de la API de la plataforma digital. Se trata de una alternativa a la API de servicio de segmento por lotes, que se usa para cargar usuarios en masa en los públicos. De forma similar a la API de servicio de segmentos por lotes, las cargas no se procesan en tiempo real y pueden tardar hasta 24 horas en completarse.

Configurar el servicio

Si es un cliente nuevo y desea comenzar a usar el Servicio de audiencia instantánea, deberá abrir un ticket y proporcionar la siguiente información:

1. ¿Está utilizando ID de usuario externos (es decir, usa mapUID para almacenar la asignación con Xandr)? Si usas identificadores de usuario externos de otro miembro, inclúyelos member_id también.
2. ¿Necesita rellenar segmentos que pertenecen a otros miembros? Si es así, proporcione el member_idsarchivo .
3. ¿Cuándo quieres que tus segmentos expiren de forma predeterminada (por ejemplo, nunca expirar, expirar dentro de 60 días, etc.)? Tenga en cuenta que si incluye EXPIRACIÓN en el bloque seg, no se usará la expiración predeterminada.
4. Las siguientes preguntas son para nuestra planificación de capacidad interna:
   • ¿Cuál es el número de ID de usuario únicos por publicación?
   • ¿Cuál es el número de publicaciones esperadas por día?
   • ¿Cuál es el número de segmentos únicos por publicación?

Autenticar

Consulte el Servicio de autenticación para obtener una descripción general sobre cómo realizar llamadas a la API de Xandr. Al igual que cualquier otro servicio, debe autenticarse 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.

Ejemplo de respuesta 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 al servicio de audiencia instantánea en el encabezado de autorización o como un access_token parámetro de 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 eliminar usuarios de segmentos

Tras la autenticación, ya está listo para agregar o quitar un usuario a o desde un segmento, mediante un archivo JSON.

En el ejemplo siguiente se muestra cómo asignar un usuario a dos segmentos. En este ejemplo, el miembro agrega el ID de usuario 12345678900987654321 (este es un ID de usuario de Xandr) a los segmentos 10001 y 10002, estableciendo ambas asociaciones con valor = 1 y expiración en 1440 minutos.

Ejemplo de 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 útil 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

seg_block array

Response

Escenarios adicionales POST

Usar el id. de dispositivo (IDFA)

Llamada API de REST (IDFA)

curl -X POST-H "Authorization: hbapi:123456:9876abcd54321:nym2"-d @json/segment.json "https://streaming-data.appnexus.com/rt-segment"

Carga útil 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 de 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 útil 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

Para cumplir con un tiempo máximo de activación de dos minutos, el servicio de audiencia instantánea tiene actualmente los siguientes límites:

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 útil 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 útil de 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
}
]
}
]
}

Escenario de respuesta (seg_id/seg_code y member_id 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 se proporciona

Carga útil de 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 útil de 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
}
]
}
]
}
}
]
}

Temas relacionados

• Segmentación Server-Side streaming
• Comprobar estadísticas de uso