EngageLab

Vue d'ensemble

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

Adresse de Callback

L'entreprise doit définir l'adresse de callback 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 callback.

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

Lors de la configuration de l'adresse de callback dans la gestion du backend Push sous Paramètres de l'application, une requête POST sera envoyée avec une chaîne de 8 caractères générée aléatoirement en tant que paramètre echostr dans le corps de la requête. 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 bien Engagelab, vous pouvez choisir d'authentifier la source des données POST. Sinon, vous pouvez directement analyser les données POST sans authentification.

La méthode d'authentification est la suivante :

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

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 callback (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 réception du callback d'Engagelab, le service développeur doit répondre dans les 3 secondes selon les exigences suivantes :

Réception réussie : Le code de statut HTTP doit retourner 200 ou 204, aucun message de réponse n'est requis.
Échec de la réception : Le code de statut HTTP doit retourner 5XX ou 4XX et un message de réponse. 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	Code d'erreur
`message`	string	Optionnel	Détails de l'erreur

Explication des champs de callback

Corps du message

Nom du champ	Type	Obligatoire/Optionnel	Description
`total`	int	Obligatoire	Nombre de messages inclus dans ce callback
`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 : `AppPush`, `WebPush`
`channel`	string	Obligatoire	Canal de message, valeurs possibles : `EngageLab`, `HuaWei`, `XiaoMi`, `MeiZu`, `OPPO`, `VIVO`, `HONOR`, `FCM`, `APNs`
`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'horodatage de chaque statut
`status`	object	Obligatoire	Informations de 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é`, `5 : Activité en temps réel iOS`, `6 : Message VOIP iOS`, `7 : Message in-app`
`platform`	string	Obligatoire	Plateforme de push, valeurs possibles : `a : Android`, `i : iOS`, `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 du SDK
`channel`	string	Obligatoire	Canal de l'application intégrée au SDK, obtenu via les données de reporting du 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 ne nécessite pas de traitement
`plan_user_total`	int	Optionnel	Ce champ n'a pas de signification réelle et ne nécessite pas de traitement
`callback_type`	int	Optionnel	Ce champ n'a pas de signification réelle et ne nécessite pas de traitement
`error_code`	int	Optionnel	Code d'erreur, fourni uniquement en cas d'échec
`error_detail`	object	Optionnel	Détails de l'erreur, fourni uniquement en cas d'échec, contenant les champs ci-dessous :
`message`	string	Optionnel	Raison détaillée de l'erreur, applicable uniquement au 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`, `HuaWei`, `XiaoMi`, `MeiZu`, `OPPO`, `VIVO`, `HONOR`, `FCM`, `APNs`
`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 au cours des 365 derniers jours
`sent`	Envoyé avec succès	Envoyé avec succès au serveur
`delivered`	Livré avec succès	Pour `EngageLab`, `XiaoMi`, `OPPO`, `VIVO` — livré selon le callback réel ; Pour `FCM` et `APNs` — livré lorsqu'il est envoyé avec succès au serveur du fournisseur ; Pour `HuaWei`, `MeiZu`, `HONOR`, si le callback fournisseur n'est pas configuré, livré lorsqu'envoyé au serveur du fournisseur ; si configuré, livré selon le callback réel du fournisseur
`click`	Clic utilisateur	Clic utilisateur rapporté par le SDK
`target_invalid`	Cible invalide	Considéré comme invalide selon l'étape 1 du tableau de perte
`sent_failed`	Échec d'envoi	Considéré comme invalide selon l'étape 2 du tableau de perte
`delivered_failed`	Échec de livraison	Considéré comme échec selon l'étape 3 du tableau de perte
`no_click`	Échec de clic	Considéré comme échec selon l'étape 4 du tableau de perte, applicable uniquement aux messages in-app

Contenu du callback

Méthode de callback : 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", // ID du message côté EngageLab "from": "", // Expéditeur "to": "", // Destinataire, registrationID "server": "AppPush", "channel": "FCM", "custom_args": {}, // Paramètres soumis lors de la création de ce message "itime": 1640707579, // ex : heure de livraison du message "status": { // Champs retournés en cas de succès "message_status": "delivered", // Statut du message "status_data": { // Données personnalisées "channel_message_id": "wamid.123321abcdefed==", // Optionnel, ID du message du canal tiers "ntf_msg": 1, // Type de message "platform": "a", // Plateforme de push "uid": 100, // ID utilisateur pour la notification push "app_version": "", // Version de l'application intégrée au SDK "channel": "", // Canal de l'application intégrée au SDK "msg_time": 1640707579, // Heure de livraison du message "time_zone": "+8", // Fuseau horaire de l'organisation "loss_valid_type": 0, // Champ non important "plan_user_total": 0, // Champ non important "callback_type": 0 // Champ non important }, // Champs retournés en cas d'échec "error_code": 0, // Code d'erreur - correspondant au code d'erreur du cycle de vie "error_detail": { "message": "" // Raison de l'erreur }, "loss": { "loss_source": "vivo", "loss_step": 1 } // Étape de perte et source de perte } } ] }

              
              {
    "total": 1,
    "rows": [
        {
            "message_id": "1666165485030094861", // ID du message côté EngageLab
            "from": "", // Expéditeur
            "to": "", // Destinataire, registrationID
            "server": "AppPush",
            "channel": "FCM",
            "custom_args": {}, // Paramètres soumis lors de la création de ce message
            "itime": 1640707579, // ex : heure de livraison du message
            "status": {
                // Champs retournés en cas de succès
                "message_status": "delivered", // Statut du message    
                "status_data": { // Données personnalisées
                    "channel_message_id": "wamid.123321abcdefed==", // Optionnel, ID du message du canal tiers
                    "ntf_msg": 1, // Type de message
                    "platform": "a", // Plateforme de push
                    "uid": 100, // ID utilisateur pour la notification push    
                    "app_version": "", // Version de l'application intégrée au SDK 
                    "channel": "", // Canal de l'application intégrée au SDK   
                    "msg_time": 1640707579, // Heure de livraison du message
                    "time_zone": "+8", // Fuseau horaire de l'organisation 
                    "loss_valid_type": 0, // Champ non important
                    "plan_user_total": 0, // Champ non important 
                    "callback_type": 0 // Champ non important
                },
                // Champs retournés en cas d'échec
                "error_code": 0, // Code d'erreur - correspondant au code d'erreur du cycle de vie
                "error_detail": {
                    "message": "" // Raison de l'erreur
                },
                "loss": {
                    "loss_source": "vivo",
                    "loss_step": 1
                } // Étape de perte et source de perte
            }
        }
    ]
}

Afficher ce bloc de code dans la fenêtre flottante

Description des paramètres

Valeur	Signification
`target_valid`	Cible effective
`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 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 Callback

Vue d'ensemble

Adresse de Callback

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

Mécanisme de sécurité

Mécanisme de réponse

Explication des champs de callback

Corps du message

Champs du tableau rows

Champs de l'objet status

Valeurs de statut du message

Contenu du callback

Exemple

En-tête de la requête

Corps de la requête

Description des paramètres

Étapes de perte

Champs du tableau `rows`

Champs de l'objet `status`