API de rappel

Vue d'ensemble

Les données de statut des messages sont rappelées vers le système métier de l'entreprise, permettant une analyse statistique basée sur ces informations.

Adresse de rappel

L'entreprise doit définir l'adresse de rappel pour recevoir les changements de statut des messages. Actuellement, il n'existe pas d'interface web. Veuillez contacter le personnel technique d'Engagelab pour configurer l'adresse de rappel.

Vérification de la validité de l'adresse de rappel

Lors de la configuration de l'adresse de rappel dans la gestion backend Push sous Paramètres de l'application, une requête POST sera envoyée avec une chaîne aléatoire de 8 caractères en tant que paramètre du corps de la requête echostr. Vous devez retourner la valeur de echostr dans le corps de la réponse, selon le format ci-dessous :

Corps de la requête :

{ "echostr": "12345678" }

              
              {
    "echostr": "12345678"
}

Afficher ce bloc de code dans la fenêtre flottante

Corps de la réponse :

12345678

12345678

Afficher ce bloc de code dans la fenêtre flottante

Mécanisme de sécurité

Utilisé pour l'authentification du client, optionnel.

Pour garantir que la source des messages est Engagelab, vous pouvez choisir d'authentifier la source des données POST. Sinon, vous pouvez analyser directement les données POST sans authentification.

La méthode d'authentification est la suivante :

Configurez un nom d'utilisateur de rappel (username) et un secret de rappel (secret) dans la console Engagelab pour l'adresse de rappel.

Récupérez X-CALLBACK-ID dans l'en-tête de la requête, comme dans l'exemple ci-dessous :

X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

              
              X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

Afficher ce bloc de code dans la fenêtre flottante

Ici :

timestamp est l'horodatage du message de rappel (au format standard),
nonce est un nombre aléatoire,
signature est l'information de signature.

La méthode de signature est la suivante :

signature=HMAC-SHA256(secret, timestamp+nonce+username)

              
              signature=HMAC-SHA256(secret, timestamp+nonce+username)

Afficher ce bloc de code dans la fenêtre flottante

Mécanisme de réponse

Après que le service développeur a reçu le rappel d'Engagelab, il doit répondre dans les 3 secondes selon les exigences suivantes :

Réception réussie : Le code de statut HTTP de la réponse doit être 200 ou 204, aucun message de réponse n'est requis.
Échec de la réception : Le code de statut HTTP de la réponse doit être 5XX ou 4XX et un message de réponse est requis. Le format est le suivant :

{ "code": 2002, "message": "error" }

              
              {
    "code": 2002,
    "message": "error"
}

Afficher ce bloc de code dans la fenêtre flottante

Champ	Type	Obligatoire/Optionnel	Description
`code`	int	Optionnel	Codes d'erreur
`message`	string	Optionnel	Détails de l'erreur

Explication des champs de rappel

Corps du message

Nom du champ	Type	Obligatoire/Optionnel	Description
`total`	int	Obligatoire	Nombre de messages inclus dans ce rappel
`rows`	array	Obligatoire	Liste des informations détaillées sur le changement de statut du message, contenant les champs ci-dessous :

Champs du tableau `rows`

Nom du champ	Type	Obligatoire/Optionnel	Description
`message_id`	string	Obligatoire	Identifiant unique du message
`from`	string	Optionnel	Expéditeur, par défaut appkey
`to`	string	Optionnel	Identifiant du destinataire (ex : `registrationID`)
`server`	string	Obligatoire	Nom du service de message, valeurs possibles : `WebPush`
`channel`	string	Obligatoire	Canal de message, valeurs possibles : `EngageLab`, `Chrome`, `Firefox`, `Safari`, `Edge`, `Opera`, `Other`
`custom_args`	object	Optionnel	Paramètres personnalisés soumis lors de la création du message, retournés tels quels
`itime`	int	Obligatoire	Horodatage réel de l'événement de statut du message, peut être utilisé avec `message_status` pour obtenir l'heure de chaque statut
`status`	object	Obligatoire	Informations sur le statut du message, contenant les champs ci-dessous :

Champs de l'objet `status`

Nom du champ	Type	Obligatoire/Optionnel	Description
`message_status`	string	Obligatoire	Statut du message, valeurs possibles : `target_valid`, `sent`, `delivered`, `click`, `target_invalid`, `sent_failed`, `delivered_failed`, `no_click`
`status_data`	object	Optionnel	Données de statut personnalisées, contenant les champs ci-dessous :
`channel_message_id`	string	Optionnel	ID du message du canal tiers
`ntf_msg`	int	Obligatoire	Type de message, valeurs possibles : `1 : Notification`, `2 : Message personnalisé`, `7 : Message in-app`
`platform`	string	Obligatoire	Plateforme de push, valeurs possibles : `b : Web`
`uid`	int	Obligatoire	UID du destinataire de la notification push
`app_version`	string	Obligatoire	Version de l'application intégrée au SDK, obtenue via les données de reporting SDK
`channel`	string	Obligatoire	Canal de l'application intégré au SDK, obtenu via les données de reporting SDK
`msg_time`	int	Obligatoire	Heure de livraison du message, moment où la requête API d'envoi du message a réussi
`time_zone`	string	Obligatoire	Fuseau horaire de l'organisation
`loss_valid_type`	int	Optionnel	Ce champ n'a pas de signification réelle et n'a pas besoin d'être traité
`plan_user_total`	int	Optionnel	Ce champ n'a pas de signification réelle et n'a pas besoin d'être traité
`callback_type`	int	Optionnel	Ce champ n'a pas de signification réelle et n'a pas besoin d'être traité
`error_code`	int	Optionnel	Code d'erreur, fourni uniquement en cas d'échec
`error_detail`	object	Optionnel	Informations détaillées sur l'erreur, fournies uniquement en cas d'échec, contenant les champs ci-dessous :
`message`	string	Optionnel	Raison détaillée de l'erreur, uniquement applicable pour le canal FCM
`loss`	object	Optionnel	Informations sur la perte, contenant les champs ci-dessous :
`loss_source`	string	Optionnel	Source de la perte, valeurs possibles : `EngageLab`, `Chrome`, `Firefox`, `Safari`, `Edge`, `Opera`, `Other`
`loss_step`	int	Optionnel	Étape de la perte, valeurs possibles : `1 : Cible planifiée → Cible valide`, `2 : Cible valide → Quantité envoyée`, `3 : Quantité envoyée → Quantité livrée`, `4 : Quantité livrée → Quantité cliquée`

Valeurs de statut du message

Valeur du statut	Signification	Description
`target_valid`	Cible valide	Considéré comme valide si actif dans les 365 derniers jours
`sent`	Envoyé avec succès	Envoyé avec succès au serveur
`delivered`	Livré avec succès	Livré sur la base d'un rappel réel
`click`	Clic utilisateur	Clic utilisateur rapporté par le SDK
`target_invalid`	Cible invalide	Considéré comme invalide selon l'étape de perte 1 définie
`sent_failed`	Échec d'envoi	Considéré comme invalide selon l'étape de perte 2 définie
`delivered_failed`	Échec de livraison	Considéré comme échec selon l'étape de perte 3 définie
`no_click`	Échec de clic	Considéré comme échec selon l'étape de perte 4 définie, s'applique uniquement aux messages in-app

Contenu du rappel

Méthode de rappel : POST
Content-Type : application/json

Exemple

En-tête de la requête

POST /developer_define_url HTTP/1.1 Content-Type: application/json

              
              POST /developer_define_url HTTP/1.1
Content-Type: application/json

Afficher ce bloc de code dans la fenêtre flottante

Corps de la requête

{ "total": 1, "rows": [ { "message_id": "1666165485030094861", "from": "", "to": "", "server": "WebPush", "channel": "Chrome", "custom_args": {}, "itime": 1640707579, "status": { "message_status": "delivered", "status_data": { "channel_message_id": "wamid.123321abcdefed==", "ntf_msg": 1, "platform": "a", "uid": 100, "app_version": "", "channel": "", "msg_time": 1640707579, "time_zone": "+8", "loss_valid_type": 0, "plan_user_total": 0, "callback_type": 0 }, "error_code": 0, "error_detail": { "message": "" }, "loss": { "loss_source": "vivo", "loss_step": 1 } } } ] }

              
              {
    "total": 1,
    "rows": [
        {
            "message_id": "1666165485030094861",
            "from": "",
            "to": "",
            "server": "WebPush",
            "channel": "Chrome",
            "custom_args": {},
            "itime": 1640707579,
            "status": {
                "message_status": "delivered",
                "status_data": {
                    "channel_message_id": "wamid.123321abcdefed==",
                    "ntf_msg": 1,
                    "platform": "a",
                    "uid": 100,
                    "app_version": "",
                    "channel": "",
                    "msg_time": 1640707579,
                    "time_zone": "+8",
                    "loss_valid_type": 0,
                    "plan_user_total": 0,
                    "callback_type": 0
                },
                "error_code": 0,
                "error_detail": {
                    "message": ""
                },
                "loss": {
                    "loss_source": "vivo",
                    "loss_step": 1
                }
            }
        }
    ]
}

Afficher ce bloc de code dans la fenêtre flottante

Description des paramètres

Valeur	Signification
`target_valid`	Cible valide
`sent`	Envoyé avec succès
`delivered`	Livré avec succès
`click`	Clic utilisateur
`target_invalid`	Cible invalide
`sent_failed`	Échec d'envoi
`delivered_failed`	Échec de livraison

Étapes de la perte

Cibles planifiées → Cibles valides
Cibles valides → Envoyé
Envoyé → Livré
Livré → Clics

Remarque :
1. Les clics et livraisons sur certains canaux peuvent être dupliqués, vous pouvez effectuer la déduplication vous-mêmes.
2. La quantité livrée et la quantité affichée ne seront pas ajustées 5 jours après la réussite de la livraison.

API de rappel

Vue d'ensemble

Adresse de rappel

Vérification de la validité de l'adresse de rappel

Mécanisme de sécurité

Mécanisme de réponse

Explication des champs de rappel

Corps du message

Champs du tableau rows

Champs de l'objet status

Valeurs de statut du message

Contenu du rappel

Exemple

En-tête de la requête

Corps de la requête

Description des paramètres

Étapes de la perte

Champs du tableau `rows`

Champs de l'objet `status`