Partilhar via

Registo de dispositivos de notificação push para programadores de aplicações

  • Artigo

Para saber mais sobre a abordagem geral para configurar notificações push no Customer Insights - Journeys, visite a descrição geral da configuração de notificações push.

Para ativar notificações push no Customer Insights - Journeys, precisa de concluir os seguintes passos:

  1. Configuração de aplicação de notificação push
  2. Mapeamento de utilizador para notificações push
  3. Registo de dispositivos para notificações push
  4. Receber notificações push em dispositivos
  5. Relatório de interação para notificações push

Este diagrama descreve os dois passos necessários para registar dispositivos e utilizadores no Customer Insights - Journeys.

Diagrama de registo de dispositivo e utilizador para notificações push.

Registo de dispositivos

Para concluir a configuração da aplicação móvel, o programador tem de registar dispositivos entre servidores. Já deve ter o token do dispositivo, o ID de utilizador do Customer Insights - Journeys (ID de contacto, ID da oportunidade potencial, ID de perfil do Customer Insights - Data) e o ID da aplicação móvel do Customer Insights - Journeys.

Após uma chamada bem-sucedida de um pedido de registo de dispositivo, há uma resposta 202. A resposta 202 indica apenas que o pedido foi aceite. Para confirmar um pedido bem-sucedido, tem de verificar o estado utilizando um webhook ou chamando o ponto final do estado diretamente.

API

Registo do dispositivo (individual)

Pedido HTTP de amostra (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%"
}

Pedido HTTP de amostra (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%"
}

Cabeçalhos:

  • x-ms-track-registration: quando verdadeiro, as informações sobre o sucesso/falha do registo são armazenadas e estão disponíveis através da API de estado de registo.
  • x-ms-callback-url: Quando não está vazio, o registo de dispositivo com falha ou bem-sucedido aciona um webhook de pedido POST.
  • x-ms-callback-url-headers: Contém um JSON serializado de um dicionário de cadeia a cadeia, representando os cabeçalhos transmitidos para pedidos de webwook. Utilizado apenas quando é definido x-ms-callback-url.

Devoluções: 202 se o pedido fornecido for válido, 400 caso contrário.

Corpo da resposta:

Quando x-ms-track-registration é verdadeiro:

{
    "RegistrationRequestId": "%GUID%"
}

Caso contrário, corpo vazio.

Definições
Nome Descrição
MobileAppId O identificador da aplicação móvel configurada no Customer Insights - Journeys.
UserId O identificador de utilizador do contacto, oportunidade potencial ou perfil do Customer Insights - Data de Customer Insights - Journeys.
ApiToken O seu token de API para autorizar o pedido.
ApnsDeviceToken O identificador de token exclusivo do dispositivo gerado pela aplicação iOS. Isto só será enviado para um dispositivo iOS
FcmDeviceToken O identificador de token exclusivo do dispositivo gerado pela aplicação Android. Isto só será enviado para um dispositivo Android

Registo do dispositivo (vários)

O corpo do registo do lote contém uma matriz de até 100 objetos que representam os pedidos de registo do dispositivo.

Pedido HTTP de amostra (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%"
    }
]

Pedido HTTP de amostra (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%"
    }
]

Cabeçalhos:

  • x-ms-track-registration:: quando verdadeiro, as informações sobre o sucesso ou falha do registo são armazenadas e estão disponíveis através da API de estado de registo.
  • x-ms-callback-url: Quando não está vazio, o registo de dispositivo com falha ou bem-sucedido aciona um webhook de pedido POST.
  • x-ms-callback-url-headers:: Contém um JSON serializado de um dicionário de cadeia a cadeia, representando os cabeçalhos transmitidos para pedidos de webwook. Utilizado apenas quando x-ms-callback-url está definido.

Devoluções: 202 se o pedido fornecido for válido, 400 caso contrário.

Corpo da resposta:

Quando x-ms-track-registration é verdadeiro: uma matriz de itens, cada ordem de item corresponde à ordem da matriz do corpo do pedido.

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

Caso contrário, corpo vazio.

Estado do registo do dispositivo

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

Corpo do pedido:

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

Devoluções: 200 se o pedido fornecido for válido, 400 caso contrário.

Corpo da resposta - uma matriz de itens:

[
    {
        "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 ordem de item corresponde à ordem da matriz RegistrationRequestIds.

Definições
Nome Descrição
RegistrationRequestIds Uma matriz de pedidos de registo individuais. Os valores são obtidos a partir da resposta das chamadas de registo. Isto só é fornecido quando o cabeçalho x-ms-track-registration foi utilizado para o registo
MobileAppId O identificador da aplicação móvel configurada no Customer Insights - Journeys.
UserId O identificador de utilizador do contacto, oportunidade potencial ou perfil do Customer Insights - Data de Customer Insights - Journeys.

Importante

Existem três razões possíveis pelas quais o estado pode ficar preso num estado "Pendente":

  1. O pedido de registo do dispositivo original tinha um token de API inválido. Para impedir que agentes mal-intencionados executem um ataque DoS contra um ambiente chamando "dispositivo de registo" e gerando limitação infinita, essas tentativas não produzem armazenamento de histórico de registo. Assim, não existem informações para verificar o êxito.
  2. O CRM permanece num estado limitado durante várias horas, fazendo com que a operação de atualização de estado falhe na execução da sua tarefa após várias tentativas.
  3. O pedido de registo do dispositivo foi feito sem o cabeçalho cx-ms-track-registration fornecido.

Webhook de estado de registo do dispositivo

Se um x-ms-status-callback-url for fornecido, o URL quando um registo de dispositivo for bem-sucedido ou falhar, o Customer Insights - Journeys acede ao valor do cabeçalho.

POST para o URL fornecido no cabeçalho c-ms-status-callback-url do pedido de registo do dispositivo.

Corpo:

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

Sugestão

Aassinatura é o hash HMACSHA256 do URL de retorno calculado utilizando o token da API como uma chave. Use o valor para verificar se Customer Insights - Journeys fez a chamada. Crie hash do URL de retorno com o token da API no lado do webhook, utilizando o mesmo algoritmo e comparando os valores.

Nota

Uma tentativa de fazer um pedido acontece uma vez. Qualquer falha na execução de um pedido faz com que a notificação seja perdida. Os tipos de falha incluem um URL de retorno incorreto, tempo limite de chamada API REST chamada ou um código de estado de resposta inesperado.

Devoluções: 202 se o pedido fornecido for válido, 400 caso contrário.

Corpo esperado: corpo vazio.

Limpeza do dispositivo (individual)

É importante remover da base de dados os dispositivos que já não são válidos para garantir o envio de mensagens com bom desempenho. Utilize a seguinte abordagem para remover combinações antigas de dispositivos, utilizadores e aplicações da tabela 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%"
}

Devoluções: 202 se o pedido fornecido for válido, 400 caso contrário.

Definições
Nome Descrição
MobileAppId O identificador da aplicação móvel configurada no Customer Insights - Journeys.
ApiToken O seu token de API para autorizar o pedido.
UserId O identificador de utilizador do contacto, oportunidade potencial ou perfil do Customer Insights - Data de Customer Insights - Journeys.
DeviceToken O identificador de token exclusivo do dispositivo gerado pela aplicação.

Limpeza de dispositivos (vários)

É importante remover da base de dados os dispositivos que já não são válidos para garantir o envio de mensagens com bom desempenho. Utilize a seguinte abordagem para remover combinações antigas de dispositivos, utilizadores e aplicações da tabela 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%"
}

Devoluções: 202 se o pedido fornecido for válido, 400 caso contrário.

Definições
Nome Descrição
MobileAppId O identificador da aplicação móvel configurada no Customer Insights - Journeys.
ApiToken O seu token de API para autorizar o pedido.
UserId O identificador de utilizador do contacto, oportunidade potencial ou perfil do Customer Insights - Data de Customer Insights - Journeys.
DeviceToken O identificador de token exclusivo do dispositivo gerado pela aplicação.