Enregistrement des appareils notification Push pour les développeurs d’applications

  • Article

Pour en savoir plus sur l’approche globale de configuration des notifications push dans Customer Insights - Journeys, consultez la présentation de la configuration des notifications push.

Pour activer les notifications Push dans Customer Insights - Journeys, vous devez suivre les étapes suivantes :

  1. Ouvrir les configurations d’application notification push
  2. Mappage des utilisateurs des notifications push
  3. Enregistrement de l’appareil pour les notifications push
  4. Réception des notifications Push sur des appareils mobiles
  5. Interactions par notification Push

Ce diagramme décrit les deux étapes nécessaires pour enregistrer les appareils et les utilisateurs dans Customer Insights - Journeys.

Dispositif de notifications push et diagramme d’enregistrement des utilisateurs.

Inscription de l’appareil

Pour effectuer la configuration de l’application mobile, le développeur doit enregistrer les appareils entre serveurs. Vous devriez déjà disposer du jeton de l’appareil, de l’ID utilisateur de Customer Insights - Journeys (ID de contact, ID de prospect, Customer Insights - Data ID de profil) et de l’ID d’application mobile de Customer Insights - Journeys.

En cas d’appel réussi d’une demande d’enregistrement d’appareil, il y a une réponse 202. La réponse 202 indique seulement que la demande a été acceptée. Pour confirmer une demande réussie, vous devez vérifier le statut en utilisant un webhook ou en appelant directement le statut point de terminaison.

API

Inscription de l’appareil (unique)

Exemple de requête HTTP (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%"
}

Exemple de requête HTTP (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%"
}

En-têtes :

  • x-ms-track-registration : lorsque cela est vrai, les informations sur la réussite/l’échec de l’enregistrement sont stockées et disponibles via l’API d’état d’enregistrement.
  • x-ms-callback-url : si non vide, l’échec ou la réussite d’un enregistrement de l’appareil déclencher le webhook de requête POST.
  • x-ms-callback-url-headers : contient un JSON sérialisé d’un dictionnaire chaîne à chaîne, représentant les en-têtes transmises pour les requêtes webhook. Utilisé uniquement lorsque x-ms-callback-url est défini.

Renvoie : 202 si la demande fournie est valide, sinon 400.

Corps de la réponse :

Lorsque x-ms-track-registration est vrai :

{
    "RegistrationRequestId": "%GUID%"
}

Sinon, corps vide.

Définitions
Nom Description
MobileAppId L’identificateur de l’application mobile configurée dans Customer Insights - Journeys.
UserId Identifiant utilisateur du contact, du prospect ou du Customer Insights - Data profil de Customer Insights - Journeys.
ApiToken Votre jeton API pour autoriser la demande.
ApnsDeviceToken L’identifiant unique du jeton de périphérique généré par l’application iOS. Celui-ci ne sera envoyé que pour un iOS appareil
FcmDeviceToken L’identifiant unique du jeton de périphérique généré par l’application Android. Celui-ci ne sera envoyé que pour un Android appareil

Inscription de l’appareil (plusieurs)

Le corps de l’enregistrement par lots contient un tableau pouvant contenir jusqu’à 100 objets représentant les demandes d’enregistrement de périphérique.

Exemple de requête HTTP (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%"
    }
]

Exemple de requête HTTP (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%"
    }
]

En-têtes :

  • x-ms-track-registration : lorsque cela est vrai, les informations sur la réussite ou l’échec de l’enregistrement sont stockées et disponibles via l’API d’état d’enregistrement.
  • x-ms-callback-url : si non vide, l’échec ou la réussite d’un enregistrement de l’appareil déclencher le webhook de requête POST.
  • x-ms-callback-url-headers : contient un JSON sérialisé d’un dictionnaire chaîne à chaîne, représentant les en-têtes transmises pour les requêtes webhook. Utilisé uniquement lorsque x-ms-callback-url est défini.

Renvoie : 202 si la demande fournie est valide, sinon 400.

Corps de la réponse :

Lorsque x-ms-track-registration est vrai : un tableau d’éléments, l’ordre de chaque élément correspond à l’ordre du tableau du corps de la requête.

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

Sinon, corps vide.

Statut d’inscription du dispositif

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

Corps de la demande :

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

Renvoie : 200 si la demande fournie est valide, sinon 400.

Coprs réponse : tableau des éléments :

[
    {
        "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
    }
]

Chaque ordre d’élément correspond à l’ordre du tableau RegistrationRequestIds .

Définitions
Nom Description
RegistrationRequestIds Une multitude de demandes d’inscription individuelles. Les valeurs sont extraites de la réponse aux appels d’enregistrement. Ceci n’est fourni que lorsque l’en-tête x-ms-track-registration a été utilisé pour l’enregistrement.
MobileAppId L’identificateur de l’application mobile configurée dans Customer Insights - Journeys.
UserId Identifiant utilisateur du contact, du prospect ou du Customer Insights - Data profil de Customer Insights - Journeys.

Important

Il existe trois raisons possibles pour lesquelles le statut peut rester bloqué dans l’état "En attente" :

  1. La demande d’enregistrement d’origine de l’appareil contenait un jeton API non valide. Pour empêcher des acteurs malveillants d’effectuer une attaque DoS contre un environnement en appelant "enregistrer le périphérique" et en générant une limitation infinie, de telles tentatives ne produisent pas de stockage de l’historique d’enregistrement. Donc aucune informations permet de vérifier le succès.
  2. Le CRM reste dans un état limité pendant plusieurs heures, ce qui entraîne l’échec de l’opération de mise à jour du statut lors de l’exécution de sa tâche après plusieurs tentatives.
  3. La demande d’enregistrement de l’appareil a été effectuée sans l’en-tête x-ms-track-registration fourni.

Webhook du statut d’inscription de l’appareil

Si un x-ms-status-callback-url est fourni comme URL lorsqu’un enregistrement d’appareil réussit ou échoue, Customer Insights - Journeys accède à la valeur du entête.

POSTez à l’URL fournie dans x-ms-status-callback-url en-tête de la demande d’enregistrement de l’appareil.

Corps :

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

Astuce

La signature est le hachage HMACSHA256 de l’URL de rappel calculé à l’aide du jeton API comme clé. Utilisez la valeur pour vérifier que Customer Insights - Journeys a effectué l’appel. Hachant l’URL de rappel avec le jeton API du côté du webhook, en utilisant le même algorithme et en comparant les valeurs.

Note

Une tentative de demande se produit une seule fois. Tout échec d’exécution d’une requête entraîne la perte de la notification. Les types d’échec incluent une URL de rappel incorrecte, un délai d’attente d’appel API REST ou un code d’état de réponse inattendu.

Renvoie : 202 si la demande fournie est valide, sinon 400.

Corps attendu : Corps vide.

Nettoyage de l’appareil (unique)

Il est important de supprimer les appareils qui ne sont plus valides de la base de données pour garantir un envoi de messages performant. Utilisez l’approche suivante pour supprimer les anciennes combinaisons d’appareils, d’utilisateurs et d’applications du tableau des appareils.

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%"
}

Renvoie : 202 si la demande fournie est valide, sinon 400.

Définitions
Nom Description
MobileAppId L’identificateur de l’application mobile configurée dans Customer Insights - Journeys.
ApiToken Votre jeton API pour autoriser la demande.
UserId Identifiant utilisateur du contact, du prospect ou du Customer Insights - Data profil de Customer Insights - Journeys.
DeviceToken L’identifiant unique du jeton de périphérique généré par l’application.

Nettoyage de périphérique (multiple)

Il est important de supprimer les appareils qui ne sont plus valides de la base de données pour garantir un envoi de messages performant. Utilisez l’approche suivante pour supprimer les anciennes combinaisons d’appareils, d’utilisateurs et d’applications du tableau des appareils.

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%"
}

Renvoie : 202 si la demande fournie est valide, sinon 400.

Définitions
Nom Description
MobileAppId L’identificateur de l’application mobile configurée dans Customer Insights - Journeys.
ApiToken Votre jeton API pour autoriser la demande.
UserId Identifiant utilisateur du contact, du prospect ou du Customer Insights - Data profil de Customer Insights - Journeys.
DeviceToken L’identifiant unique du jeton de périphérique généré par l’application.