Compartir por

Rexistro do dispositivo de notificación push para desenvolvedores de aplicacións

  • Artigo

Para obter máis información sobre o enfoque xeral para configurar as notificacións push en Customer Insights - Journeys, visita a descrición xeral da configuración de notificacións push.

Para activar as notificacións push en Customer Insights - Journeys, debes seguir os seguintes pasos:

  1. Configuración da aplicación de notificación push
  2. Asignación de usuarios para notificacións push
  3. Rexistro do dispositivo para notificacións push
  4. Recibindo notificacións push en dispositivos
  5. Informes de interacción para notificacións push

Este diagrama describe os dous pasos necesarios para rexistrar dispositivos e usuarios dentro Customer Insights - Journeys.

Dispositivo de notificacións push e diagrama de rexistro de usuarios.

Rexistro do dispositivo

Para completar a configuración da aplicación móbil, o programador debe rexistrar os dispositivos en servidores. Xa deberías ter o token do dispositivo, o ID de usuario de Customer Insights - Journeys (ID de contacto, ID de cliente potencial, Customer Insights - Data ID de perfil) e o ID da aplicación móbil de Customer Insights - Journeys.

Tras a chamada correcta dunha solicitude de rexistro do dispositivo, hai unha resposta 202. A resposta 202 só indica que a solicitude foi aceptada. Para confirmar unha solicitude exitosa, cómpre comprobar o estado mediante un webhook ou chamando directamente ao punto final de estado.

API

Rexistro do dispositivo (único)

Solicitude HTTP de exemplo (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%"
}

Solicitude HTTP de exemplo (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: se é verdadeiro, a información sobre o éxito/fallo do rexistro gárdase e estará dispoñible a través da API de estado de rexistro.
  • x-ms-callback-url: Cando non está baleiro, un rexistro do dispositivo errado ou exitoso activa o webhook de solicitude POST.
  • x-ms-callback-url-headers: Contén un JSON serializado dun dicionario de cadea a cadea, que representa as cabeceiras pasadas para as solicitudes de webhook. Utilízase só cando se define x-ms-callback-url.

Devolucións: 202 se a solicitude proporcionada é válida, 400 en caso contrario.

Órgano de resposta:

Cando x-ms-track-registration é verdadeiro:

{
    "RegistrationRequestId": "%GUID%"
}

En caso contrario, corpo baleiro.

Definicións
Nome Descripción
MobileAppId O identificador da aplicación móbil configurada en Customer Insights - Journeys.
Identificador do usuario O identificador de usuario do contacto, cliente potencial ou Customer Insights - Data perfil de Customer Insights - Journeys.
ApiToken O teu token da API para autorizar a solicitude.
ApnsDeviceToken O identificador único do token do dispositivo xerado pola aplicación iOS . Isto só se enviará para un iOS dispositivo
FcmDeviceToken O identificador único do token do dispositivo xerado pola aplicación Android . Isto só se enviará para un Android dispositivo

Rexistro de dispositivos (múltiples)

O corpo do rexistro do lote contén unha matriz de ata 100 obxectos que representan solicitudes de rexistro do dispositivo.

Solicitude HTTP de exemplo (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%"
    }
]

Solicitude HTTP de exemplo (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: cando é verdadeira, a información sobre o éxito ou o erro do rexistro gárdase e estará dispoñible a través da API de estado de rexistro.
  • x-ms-callback-url: cando non está baleiro, un rexistro do dispositivo fallido ou correcto desencadea un POST webhook de solicitude.
  • x-ms-callback-url-headers: contén un JSON serializado dun dicionario de cadea a cadea, que representa as cabeceiras pasadas para as solicitudes de webhook. Utilízase só cando se define x-ms-callback-url .

Devolucións: 202 se a solicitude proporcionada é válida, 400 en caso contrario.

Órgano de resposta:

Cando x-ms-track-registration é verdadeiro: unha matriz de elementos, a orde de cada elemento corresponde á orde da matriz do corpo da solicitude.

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

En caso contrario, corpo baleiro.

Estado de rexistro do dispositivo

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

Órgano de solicitude:

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

Devolucións: 200 se a solicitude proporcionada é válida, 400 no caso contrario.

Corpo da resposta: unha 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
    }
]

Cada pedido de artigos corresponde á orde da matriz RegistrationRequestIds .

Definicións
Nome Descripción
Identificación da solicitude de rexistro Unha variedade de solicitudes de rexistro individuais. Os valores tómanse da resposta das chamadas de rexistro. Isto só se proporciona cando se utilizou a cabeceira x-ms-track-registration para o rexistro
MobileAppId O identificador da aplicación móbil configurada en Customer Insights - Journeys.
Identificador do usuario O identificador de usuario do contacto, cliente potencial ou Customer Insights - Data perfil de Customer Insights - Journeys.

Importante

Hai tres posibles motivos polos que o estado pode quedar atascado nun estado "Pendente":

  1. A solicitude de rexistro orixinal do dispositivo tiña un token de API non válido. Para evitar que actores maliciosos realicen un ataque DoS contra un ambiente chamando "rexister device" e xerando unha limitación infinita, tales intentos non producen o almacenamento do historial de rexistro. Polo tanto, non hai información para comprobar o éxito.
  2. O CRM permanece en estado limitado durante varias horas, o que fai que a operación de actualización de estado falle ao executar o seu traballo despois de varios intentos.
  3. A solicitude de rexistro do dispositivo realizouse sen que se proporcionou a cabeceira x-ms-track-registration .

Webhook de estado de rexistro do dispositivo

Se se fornece un x-ms-status-callback-url o URL cando o rexistro dun dispositivo se realiza correctamente ou non, Customer Insights - Journeys accede ao valor do cabeceira.

PUBLICAR no URL proporcionado dentro de x-ms-status-callback-url cabeceira da solicitude de rexistro do dispositivo.

Corpo:

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

Suxestión

A sinatura é o hash HMACSHA256 do URL de devolución de chamada calculado usando o token da API como clave. Use o valor para verificar que Customer Insights - Journeys se fixo a chamada. Haxa o URL de devolución de chamada co token da API do lado do webhook usando o mesmo algoritmo e comparando os valores.

Nota

O intento de facer unha solicitude ocorre unha vez. Calquera falta de execución dunha solicitude provoca a perda da notificación. Os tipos de erros inclúen un URL de devolución de chamada incorrecto, o tempo de espera da chamada da API REST ou un código de estado de resposta inesperado.

Devolucións: 202 se a solicitude proporcionada é válida, 400 en caso contrario.

Corpo esperado: corpo baleiro.

Limpeza do dispositivo (individual)

É importante eliminar da base de datos os dispositivos que xa non son válidos para garantir un envío de mensaxes eficiente. Use o seguinte enfoque para eliminar as combinacións antigas de dispositivos, usuarios e aplicacións da táboa 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%"
}

Devolucións: 202 se a solicitude proporcionada é válida, 400 en caso contrario.

Definicións
Nome Descripción
MobileAppId O identificador da aplicación móbil configurada en Customer Insights - Journeys.
ApiToken O teu token da API para autorizar a solicitude.
Identificador do usuario O identificador de usuario do contacto, cliente potencial ou Customer Insights - Data perfil de Customer Insights - Journeys.
DeviceToken O identificador único do token do dispositivo xerado pola aplicación.

Limpeza de dispositivos (múltiples)

É importante eliminar da base de datos os dispositivos que xa non son válidos para garantir un envío de mensaxes eficiente. Use o seguinte enfoque para eliminar as combinacións antigas de dispositivos, usuarios e aplicacións da táboa 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%"
}

Devolucións: 202 se a solicitude proporcionada é válida, 400 en caso contrario.

Definicións
Nome Descripción
MobileAppId O identificador da aplicación móbil configurada en Customer Insights - Journeys.
ApiToken O teu token da API para autorizar a solicitude.
Identificador do usuario O identificador de usuario do contacto, cliente potencial ou Customer Insights - Data perfil de Customer Insights - Journeys.
DeviceToken O identificador único do token do dispositivo xerado pola aplicación.