Compartir a través de

Notificación de inserción de registro de dispositivo para desarrolladores de aplicación

  • Artículo

Para obtener más información sobre el enfoque general para configurar notificaciones de inserción en Customer Insights - Journeys, visite la descripción general de la configuración de notificaciones de inserción.

Para habilitar las notificaciones automáticas en Customer Insights - Journeys, debe completar los siguientes pasos:

  1. Configuración de notificación de inserción de aplicación
  2. Asignación de usuarios para notificaciones de inserción
  3. Registro de dispositivo para notificaciones de inserción
  4. Recibir notificaciones de inserción en dispositivos
  5. Informes de interacciones de notificaciones de inserción

Este diagrama describe los dos pasos necesarios para registrar dispositivos y usuarios dentro de Customer Insights - Journeys.

Diagrama de dispositivo de notificaciones de inserción y registro de usuarios.

Registro del dispositivo

Para completar la configuración de la aplicación móvil, el desarrollador debe registrar dispositivos en todos los servidores. Ya debería tener el token del dispositivo, el ID de usuario de Customer Insights - Journeys (ID de contacto, ID de cliente potencial, Customer Insights - Data ID de perfil) y el ID de la aplicación móvil de Customer Insights - Journeys.

Tras una llamada exitosa de una solicitud de registro de dispositivo, hay una respuesta 202. La respuesta 202 solo indica que la solicitud fue aceptada. Para confirmar una solicitud exitosa, debe verificar el estado mediante un webhook o llamando al estado punto de conexión directamente.

API

Registro de dispositivo (individual)

Solicitud HTTP de ejemplo (iOS):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "ApiToken": "%API_TOKEN%",
    "ApnsDeviceToken": "%APNS_TOKEN%"
}

Solicitud HTTP de ejemplo (Android):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "ApiToken": "%API_TOKEN%",
    "FcmDeviceToken": "%FCM_TOKEN%"
}

Encabezados:

  • x-ms-track-registration: cuando es verdadero, la información sobre el éxito o el fracaso del registro se almacena y estará disponible a través de la API de estado de registro.
  • x-ms-callback-url: cuando no está vacío, un registro de error o correcto del dispositivo desencadenará el webhook de solicitud POST.
  • x-ms-callback-url-headers: contiene un JSON serializado de un diccionario de cadena a cadena, que representa los encabezados pasados ​​para solicitudes de webhook. Se utiliza solo cuando se define x-ms-callback-url.

Devoluciones: 202 se proporciona si la solicitud es válida, 400 de lo contrario.

Cuerpo de la respuesta:

Cuando x-ms-track-registration es verdadero:

{
    "RegistrationRequestId": "%GUID%"
}

De lo contrario, cuerpo vacío.

Definiciones
Nombre Descripción
MobileAppId El identificador de la aplicación móvil configurada en Customer Insights - Journeys.
UserId El identificador de usuario del contacto, cliente potencial o perfil de Customer Insights - Data de Customer Insights - Journeys.
Token de Api Su token API para autorizar la solicitud.
ApnsDeviceToken El identificador de token de dispositivo único generado por la aplicación iOS. Esto solo se enviará para un dispositivo iOS
FcmDeviceToken El identificador de token de dispositivo único generado por la aplicación Android. Esto solo se enviará para un dispositivo Android

Registro de dispositivo (múltiple)

El cuerpo del registro por lotes contiene una matriz de hasta 100 objetos que representan solicitudes de registro de dispositivos.

Solicitud HTTP de ejemplo (iOS):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/batch

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    }
]

Solicitud HTTP de ejemplo (Android):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/batch

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    }
]

Encabezados:

  • x-ms-track-registration:: cuando es verdadero, la información sobre el éxito o el fracaso del registro se almacena y estará disponible a través de la API de estado de registro.
  • x-ms-callback-url: cuando no está vacío, un registro de error o correcto del dispositivo desencadenará el webhook de solicitud POST.
  • x-ms-callback-url-headers:: contiene un JSON serializado de un diccionario de cadena a cadena, que representa los encabezados pasados ​​para solicitudes de webhook. Se utiliza sólo cuando x-ms-callback-url se define.

Devoluciones: 202 se proporciona si la solicitud es válida, 400 de lo contrario.

Cuerpo de la respuesta:

Cuando x-ms-track-registration es verdadero: una matriz de elementos, el orden de cada elemento corresponde al pedido de la matriz del cuerpo de la solicitud.

[
    {
        "RegistrationRequestId": "%REG_REQUEST_ID%"
    },
    {
        "RegistrationRequestId": "%REG_REQUEST_ID%"
    }
]

De lo contrario, cuerpo vacío.

Estado de registro de dispositivo

POST  {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/status/

Cuerpo de la solicitud:

{
    "RegistrationRequestIds": [
        "%REG_REQUEST_ID%"
    ],
    "MobileAppId": "%MOBILE_APP_ID%",
    "ApiToken": "%API_TOKEN%"
}

Devoluciones: 200 se proporciona si la solicitud es válida, 400 de lo contrario.

Cuerpo de la respuesta - una matriz de elementos:

[
    {
        "Status": "Pending|Success|Failed",
        "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid " // dry run sending is a verification of device token by sending an invisible notification to mobile app. Such sending failure might happen due to a wrong device token or incorrect/expired mobile app auth data
    },
    {
        "Status": "Pending|Success|Failed",
        "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid " // dry run sending is a verification of device token by sending an invisible notification to mobile app. Such sending failure might happen due to a wrong device token or incorrect/expired mobile app auth data
    }
]

El pedido de cada artículo corresponde al pedido de la matriz RegistrationRequstIds.

Definiciones
Nombre Descripción
RegistrationRequestIds Una variedad de solicitudes de registro individuales. Los valores se toman de la respuesta de las llamadas de registro. Esto solo se proporciona cuando el encabezado x-ms-track-registration se utilizó para el registro
MobileAppId El identificador de la aplicación móvil configurada en Customer Insights - Journeys.
UserId El identificador de usuario del contacto, cliente potencial o perfil de Customer Insights - Data de Customer Insights - Journeys.

Importante

Hay tres posibles razones por las que el estado puede quedarse atascado en el estado "Pendiente":

  1. La solicitud de registro del dispositivo original tenía un token API no válido. Para evitar que actores malintencionados realicen un ataque DoS contra un entorno llamando al "dispositivo de registro" y generando una limitación infinita, dichos intentos no generan almacenamiento del historial de registro. Por lo tanto, no hay información para verificar el éxito.
  2. El CRM permanece en un estado limitado durante varias horas, lo que provoca que la operación de actualización de estado no pueda ejecutar su trabajo después de varios reintentos.
  3. La solicitud de registro del dispositivo se realizó sin el encabezado x-ms-track-registration proporcionado.

Webhook de estado de registro de dispositivo

Si se proporciona un x-ms-status-callback-url la URL cuando el registro de un dispositivo es exitoso o fallido, Customer Insights - Journeys accede al valor del encabezado.

POST en la URL proporcionada dentro del encabezado x-ms-status-callback-url encabezado de la solicitud de registro del dispositivo.

Cuerpo:

{ 
    "Status": "Success|Failed", 
    "Signature": "%SIGNATURE%", 
    "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid" 
}

Propina

La firma es el hash HMACSHA256 de la URL de devolución de llamada calculada utilizando el token API como clave. Utilice el valor para verificar que Customer Insights - Journeys hizo la llamada. Hash a la URL de devolución de llamada con el token de API en el lado del webhook, usando el mismo algoritmo y comparando los valores.

Nota

El intento de realizar una solicitud ocurre una vez. Cualquier error en la ejecución de una solicitud hace que se pierda la notificación. Los tipos de error incluyen una URL de devolución de llamada incorrecta, tiempo de espera de llamada API de REST o código de estado de respuesta inesperado.

Devoluciones: 202 se proporciona si la solicitud es válida, 400 de lo contrario.

Cuerpo esperado: cuerpo vacío.

Limpieza del dispositivo (único)

Es importante eliminar de la base de datos los dispositivos que ya no son válidos para garantizar un envío de mensajes eficaz. Utilice el siguiente método para eliminar combinaciones antiguas de dispositivos, usuarios y aplicaciones de la tabla de dispositivos.

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/cleanup

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

Devoluciones: 202 se proporciona si la solicitud es válida, 400 de lo contrario.

Definiciones
Nombre Descripción
MobileAppId El identificador de la aplicación móvil configurada en Customer Insights - Journeys.
Token de Api Su token API para autorizar la solicitud.
UserId El identificador de usuario del contacto, cliente potencial o perfil de Customer Insights - Data de Customer Insights - Journeys.
DeviceToken El identificador de token de dispositivo único generado por la aplicación.

Limpieza del dispositivo (múltiple)

Es importante eliminar de la base de datos los dispositivos que ya no son válidos para garantizar un envío de mensajes eficaz. Utilice el siguiente método para eliminar combinaciones antiguas de dispositivos, usuarios y aplicaciones de la tabla de dispositivos.

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/cleanup/batch

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

Devoluciones: 202 se proporciona si la solicitud es válida, 400 de lo contrario.

Definiciones
Nombre Descripción
MobileAppId El identificador de la aplicación móvil configurada en Customer Insights - Journeys.
Token de Api Su token API para autorizar la solicitud.
UserId El identificador de usuario del contacto, cliente potencial o perfil de Customer Insights - Data de Customer Insights - Journeys.
DeviceToken El identificador de token de dispositivo único generado por la aplicación.