Compartilhar via

Registro do dispositivo de notificação por push para desenvolvedores de aplicativo

  • Artigo

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

Para habilitar notificações por push no Customer Insights - Journeys, você precisa concluir as seguintes etapas:

  1. Configuração do aplicativo de notificação por push
  2. Mapeamento de usuário para notificações por push
  3. Registro do dispositivo para notificações por push
  4. Recebimento de notificações por push em dispositivos
  5. Relatório de interação para notificações por push

Este diagrama descreve as duas etapas necessárias para registrar dispositivos e usuários dentro do Customer Insights - Journeys.

Dispositivo de notificações por push e diagrama de registro do usuário.

Registro de dispositivo

Para concluir a configuração do aplicativo móvel, o desenvolvedor deve registrar dispositivos nos servidores. Você já deve ter o token do dispositivo, a ID do usuário do Customer Insights - Journeys (ID do contato, ID do cliente potencial, ID do perfil do Customer Insights - Data) e a ID do aplicativo móvel do Customer Insights - Journeys.

Depois da chamada bem-sucedida de uma solicitação de registro do dispositivo, haverá uma resposta 202. A resposta 202 só indica que a solicitação foi aceita. Para confirmar uma solicitação bem-sucedida, você precisa verificar o status usando um webhook ou chamando diretamente o ponto de extremidade de status.

API

Registro do dispositivo (único)

Solicitação HTTP de amostra (iOS):

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

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "ApnsDeviceToken": "%APNS_TOKEN%"
}

Solicitação HTTP de amostra (Android):

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

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "FcmDeviceToken": "%FCM_TOKEN%"
}

Cabeçalhos:

  • x-ms-track-registration: quando verdadeiras, as informações sobre êxito/falha no registro são armazenadas e disponibilizadas por meio da API de status do registro.
  • x-ms-callback-url: quando não está vazio, um registro do dispositivo com falha ou êxito dispara o webhook de solicitação POST.
  • x-ms-callback-url-headers: contém um JSON serializado de um dicionário de cadeia de caracteres para cadeia de caracteres, representando cabeçalhos passados para solicitações de webhook. Só usado quando x-ms-callback-url é definido.

Retorna: 202 se a solicitação fornecida for válida; do contrário, 400.

Corpo da resposta:

Quando x-ms-track-registration for verdadeiro:

{
    "RegistrationRequestId": "%GUID%"
}

Do contrário, corpo vazio.

Definições
Nome Descrição
MobileAppId O identificador do aplicativo móvel configurado no Customer Insights - Journeys.
UserId O identificador do usuário do contato, do cliente potencial ou do perfil do Customer Insights - Data do Customer Insights - Journeys.
ApiToken O token de API para autorizar a solicitação.
ApnsDeviceToken O identificador de token do dispositivo exclusivo gerado pelo aplicativo iOS. Isso só vai ser enviado para um dispositivo iOS
FcmDeviceToken O identificador de token do dispositivo exclusivo gerado pelo aplicativo Android. Isso só vai ser enviado para um dispositivo Android

Registro do dispositivo (vários)

O corpo do registro em lote contém uma matriz de até 100 objetos que representam solicitações de registro do dispositivo.

Solicitação HTTP de amostra (iOS):

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

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00000000-0000-0000-0000-000000000000",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00000000-0000-0000-0000-000000000000",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    }
]

Solicitação HTTP de amostra (Android):

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

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00000000-0000-0000-0000-000000000000",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00000000-0000-0000-0000-000000000000",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    }
]

Cabeçalhos:

  • x-ms-track-registration:: quando verdadeiras, as informações sobre êxito ou falha no registro são armazenadas e disponibilizadas por meio da API de status do registro.
  • x-ms-callback-url: quando não está vazio, um registro do dispositivo com falha ou êxito dispara um webhook de solicitação POST.
  • x-ms-callback-url-headers:: contém um JSON serializado de um dicionário de cadeia de caracteres para cadeia de caracteres, representando cabeçalhos passados para solicitações de webhook. Só usado quando x-ms-callback-url é definido.

Retorna: 202 se a solicitação fornecida for válida; do contrário, 400.

Corpo da resposta:

Quando x-ms-track-registration for verdadeiro: uma matriz de itens, cada ordem de item corresponde à ordem da matriz do corpo de solicitação.

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

Do contrário, corpo vazio.

Status de registro do dispositivo

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

Corpo da solicitação:

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

Retorna: 200 se a solicitação fornecida for válida; do contrário, 400.

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 do item corresponde à ordem da matriz RegistrationRequestIds.

Definições
Nome Descrição
RegistrationRequestIds Uma matriz das solicitações de registro individual. Os valores são utilizados da resposta das chamadas de registro. Isso só é fornecido quando o cabeçalho x-ms-track-registration foi usado para registro
MobileAppId O identificador do aplicativo móvel configurado no Customer Insights - Journeys.
UserId O identificador do usuário do contato, do cliente potencial ou do perfil do Customer Insights - Data do Customer Insights - Journeys.

Importante

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

  1. A solicitação de registro do dispositivo original tinha um token de API inválido. Para evitar que agentes mal-intencionados realizem um ataque DoS contra um ambiente chamando um "dispositivo de registro" e gerando uma limitação infinita, essas tentativas não produzem armazenamento do histórico de registro. Por isso, não existem informações para verificar o êxito.
  2. O CRM permanece em um estado limitado por várias horas, fazendo com que a operação de atualização do status falhe durante a execução do trabalho após várias tentativas.
  3. A solicitação de registro do dispositivo foi feita sem o cabeçalho x-ms-track-registration fornecido.

Webhook de status do registro de dispositivo

Se um x-ms-status-callback-url receber a URL quando um registro de dispositivo for bem-sucedido ou falhar, o Customer Insights - Journeys vai acessar o valor do cabeçalho.

POST para a URL fornecida dentro do cabeçalho x-ms-status-callback-url da solicitação de registro do dispositivo.

Corpo:

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

Dica

A assinatura é o hash HMACSHA256 da URL de retorno de chamada calculado usando-se o token de API como chave. Use o valor para verificar se o Customer Insights - Journeys fez a chamada. Faça hash da URL de retorno de chamada com o token da API no lado do webhook usando o mesmo algoritmo e comparando os valores.

Observação

Uma tentativa de fazer uma solicitação acontece uma vez. Qualquer falha na execução de uma solicitação faz com que a notificação seja perdida. Entre os tipos de falha estão uma URL de retorno de chamada incorreta, tempo limite da chamada à API REST ou código de status da resposta inesperada.

Retorna: 202 se a solicitação fornecida for válida; do contrário, 400.

Corpo esperado: corpo vazio.

Limpeza do dispositivo (único)

É importante remover dispositivos que deixaram de ser válidos do banco de dados para garantir o bom envio das mensagens. Use a abordagem a seguir para remover combinações anteriores de dispositivo, usuário e aplicativo 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": "00000000-0000-0000-0000-000000000000",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

Retorna: 202 se a solicitação fornecida for válida; do contrário, 400.

Definições
Nome Descrição
MobileAppId O identificador do aplicativo móvel configurado no Customer Insights - Journeys.
ApiToken O token de API para autorizar a solicitação.
UserId O identificador do usuário do contato, do cliente potencial ou do perfil do Customer Insights - Data do Customer Insights - Journeys.
DeviceToken O identificador de token do dispositivo exclusivo gerado pelo aplicativo.

Limpeza do dispositivo (vários)

É importante remover dispositivos que deixaram de ser válidos do banco de dados para garantir o bom envio das mensagens. Use a abordagem a seguir para remover combinações anteriores de dispositivo, usuário e aplicativo 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": "00000000-0000-0000-0000-000000000000",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

Retorna: 202 se a solicitação fornecida for válida; do contrário, 400.

Definições
Nome Descrição
MobileAppId O identificador do aplicativo móvel configurado no Customer Insights - Journeys.
ApiToken O token de API para autorizar a solicitação.
UserId O identificador do usuário do contato, do cliente potencial ou do perfil do Customer Insights - Data do Customer Insights - Journeys.
DeviceToken O identificador de token do dispositivo exclusivo gerado pelo aplicativo.