API de Audiencia

Nota

El request_id utilizado en esta página es un token de trabajo para sondear el estado de una operación bulk*, no relacionado con el ID de Solicitud del mensaje utilizado para el rastreo a nivel de HTTP.

bulkSetTags

POST https://api.pushwoosh.com/api/v2/audience/bulkSetTags

Establece los valores de las etiquetas para la lista de dispositivos.

Importante

Al utilizar el método bulkSetTags, asegúrese de que los valores de las etiquetas se establezcan para un mínimo de 50 dispositivos. Para establecer etiquetas para un solo dispositivo, utilice el método setTags.

Cuerpo de la solicitud

Nombre	Tipo	Descripción
application*	String	Código de aplicación de Pushwoosh
auth*	String	Token de acceso a la API desde el Panel de Control de Pushwoosh.
create_missing_tags	Boolean	Si es verdadero, las etiquetas faltantes se crean automáticamente.
devices*	Object	Array de dispositivos.
devices.hwid	String	Se puede usar para identificar un dispositivo en lugar de user_id o push_token. Aprenda más
devices.user_id	String	Se puede usar para identificar un usuario en lugar de hwid o push_token. Aprenda más
devices.push_token	String	Se puede usar para identificar un dispositivo en lugar de hwid o user_id. Aprenda más
devices.list_operator	String	Define cómo establecer valores para etiquetas del tipo lista: set, append o remove
devices.tags*	Object	Valores a establecer para las etiquetas especificadas.

OK

{
  "request_id": "request_id to use in GET method to obtain job status",
  "status": "Pending"
}

Error

{
  "message": "invalid request"
}

Solicitud:

{
  "application": "application code",   // required. Pushwoosh app code
  "auth": "Pushwoosh auth token",      // required. API access token from Pushwoosh Control Panel
  "create_missing_tags": false,        // optional. Should automatically create missing tags
  "devices": [{                        // required. Array of devices
    "hwid": "device hwid",             // optional. Can be used to identify a device instead of
                                       //           "user_id" or "push_token".
    "user_id": "user ID",              // optional. Can be used to identify a user instead of "hwid" or "push_token".
    "push_token": "device push token", // optional. Can be used to identify a device instead of "hwid" or "user_id".
    "list_operator": "set",            // required. For list tags. Defines how to set values for
                                       //           tags of the list type: set, append, or remove
    "tags": {                          // required. Values to set for the tags specified.
      "tag_name": "tagvalue",          //           use correct value type
      "tag_name2": "tagvalue2"
    }
  }]
}

Respuesta:

{
  "request_id": "request_id to use in GET method to obtain job status",
  "status": "Pending"
}

Estado de bulkSetTags

GET https://api.pushwoosh.com/api/v2/audience/bulkSetTags/{request_id}?detailed=false

Devuelve el estado de la operación /bulkSetTags

Parámetros de ruta

Nombre	Tipo	Descripción
request_id	String	ID de solicitud de la llamada /bulkSetTags anterior

Parámetros de consulta

Nombre	Tipo	Descripción
detailed	Boolean	(true/false) si se debe devolver información detallada por dispositivo

Respuesta:

{
  "request_id": "id of the request",
  "status": "Completed",          // also "Pending", "Failed"
  "progress": 100,                // jobs progress 0-100
  "devices_success": 100,         // good devices
  "devices_not_found": 0,         // devices not found in Pushwoosh
  "devices_failed": 0,            // errored
  "devices": [{                   // device report (only in detailed = true)
    "hwid": "device hwid",
    "status": "done",             // also "failed", "not found"
    "tags": {
      "tagName": "ok",
      "tagName2": "tag not found",
      "tagName3": "wrong value. expect :string"
    }
  }]
}

bulkRegisterDevice

Registra múltiples dispositivos en Pushwoosh en una sola solicitud. También permite especificar varias etiquetas para cada dispositivo.

POST https://api.pushwoosh.com/api/v2/audience/bulkRegisterDevice

Parámetros del cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
application	string	Sí	Código de aplicación de Pushwoosh
auth	string	Sí	Token de acceso a la API.
devices	array	Sí	Un array de objetos de dispositivo. Cada objeto representa un dispositivo y sus datos asociados. Vea los detalles en la tabla de Parámetros del objeto de dispositivo a continuación.

Parámetros del objeto de dispositivo

Parámetro	Tipo	Requerido	Descripción
hwid	string	Sí	El ID de hardware o identificador único para el dispositivo.
push_token	string	Sí	Token push para el dispositivo.
platform	integer	Sí	El identificador de la plataforma. Aprenda más
list_operator	string	No	Determina la acción para las etiquetas de tipo lista: - “append”: Añade el valor especificado a la lista de etiquetas. - “remove”: Elimina el valor especificado de la lista de etiquetas. Nota: Si no se especifica el parámetro list_operator, todos los valores existentes en la lista de etiquetas serán reemplazados por los valores proporcionados.
tags	object	No	Etiquetas personalizadas asignadas al dispositivo. Las etiquetas son pares clave-valor utilizados para la segmentación.

Ejemplo de solicitud

{
  "application": "application code",   // required. Pushwoosh app code
  "auth": "Pushwoosh auth token",      // required. API access token from Pushwoosh Control Panel
  "devices": [{                        // required. Array of devices
    "hwid": "device hwid",             // required. Unique identifier for the device (can be an email).
    "push_token": "device push token", // required. Push notification token for the device.
    "platform": 14,                    // required. Device platform (e.g., 14 for email).
    "list_operator": "append",         // optional. For list tags. Adds or removes the specified value(s) from the tag of list type.
    "tags": {                          // optional. Values to set for the specified tags.
      "language": "en",                //           use correct value type.
      "CSV_Import": "summer_camp"
    }
  },
  {
    "hwid": "device hwid 2",           // required. Unique identifier for the second device.
    "push_token": "device push token 2", // required. Push notification token for the device.
    "platform": 14,                    // required. Device platform.
    "list_operator": "remove",         // optional. Adds or removes values from tags of the list type.
    "tags": {                          // optional. Values to remove from the specified tags.
      "language": "en",
      "CSV_Import": "summer_camp2"
    }
  },
  {
    "hwid": "device hwid 3",           // required. Unique identifier for the third device.
    "push_token": "device push token 3", // required. Push notification token for the device.
    "platform": 14,                    // required. Device platform.
    "tags": {                          // optional. Values to set for the specified tags.
      "language": "en",
      "CSV_Import": "summer_camp3"
    }
  }]
}

Respuesta

El método responde con un ID de operación, que se puede utilizar para rastrear el estado y los resultados del proceso de registro masivo.

{
  "request_id": "request_id to use in GET method to obtain job status",
  "status": "Pending"
}

Estado de bulkRegisterDevice

Puede verificar el estado de un proceso de registro masivo realizando la siguiente solicitud GET:

GET https://api.pushwoosh.com/api/v2/audience/bulkRegisterDevice/{request_id}?detailed=true

Parámetro	Tipo	Requerido	Descripción
request_id	string	Sí	El ID de solicitud devuelto por la solicitud POST.
detailed	boolean	No	Si se establece en true, la respuesta incluye resultados detallados para cada dispositivo registrado.

Ejemplo de respuesta

{
  "request_id": "9a2e1a14-XXXX-46c3-XXXX-c254b25d3782",
  "status": "Completed",
  "progress": 100,
  "devices_success": 4,
  "devices": [
    {
      "hwid": "user1@example.com",
      "status": "done"
    },
    {
      "hwid": "user2@example.com",
      "status": "done"
    },
    {
      "hwid": "user3@example.com",
      "status": "done"
    },
    {
      "hwid": "invalid_email@example.com",
      "status": "failed"
    }
  ]
}

bulkUnregisterDevice

Da de baja múltiples dispositivos de Pushwoosh en una sola solicitud.

POST https://api.pushwoosh.com/api/v2/audience/bulkUnregisterDevice

Parámetros del cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
application	string	Sí	Código de aplicación de Pushwoosh
auth	string	Sí	Token de acceso a la API
devices	array	Sí	Un array de objetos de dispositivo. Cada objeto representa un dispositivo y sus datos asociados. Vea los detalles en la tabla de Parámetros del objeto de dispositivo a continuación.

Parámetros del objeto de dispositivo

Parámetro	Tipo	Requerido	Descripción
hwid	string	Sí	El ID de hardware o identificador único para el dispositivo. Aprenda más

Ejemplo de solicitud

{
  "application": "application code",   // required. Pushwoosh app code
  "auth": "Pushwoosh auth token",      // required. API access token from Pushwoosh Control Panel
  "devices": [{                        // required. Array of devices
    "hwid": "device hwid",             // required. Unique identifier for the device (can be an email).
  },
  {
    "hwid": "device hwid 2",           // required. Unique identifier for the second device.
  },
  {
    "hwid": "device hwid 3",           // required. Unique identifier for the third device.
  }]
}

Respuesta

El método responde con un ID de operación, que se puede utilizar para rastrear el estado y los resultados del proceso masivo.

{
  "request_id": "request_id to use in GET method to obtain job status",
  "status": "Pending"
}

Estado de bulkUnregisterDevice

Puede verificar el estado de un proceso de baja masiva realizando la siguiente solicitud GET:

GET https://api.pushwoosh.com/api/v2/audience/bulkUnregisterDevice/{request_id}?detailed=true

Parámetro	Tipo	Requerido	Descripción
request_id	string	Sí	El ID de solicitud devuelto por la solicitud POST.
detailed	boolean	No	Si se establece en true, la respuesta incluye resultados detallados para cada dispositivo dado de baja.

Ejemplo de respuesta

{
  "request_id": "9a2e1a14-XXXX-46c3-XXXX-c254b25d3782",
  "status": "Completed",
  "progress": 100,
  "devices_success": 4,
  "devices": [
    {
      "hwid": "user1@example.com",
      "status": "done"
    },
    {
      "hwid": "user2@example.com",
      "status": "done"
    },
    {
      "hwid": "user3@example.com",
      "status": "done"
    },
    {
      "hwid": "invalid_email@example.com",
      "status": "failed"
    }
  ]
}