API Web SDK
Authentification
Lors de l'initialisation, le développeur doit fournir les informations nécessaires. Cette structure de données est générée par le serveur du développeur et renvoyée au navigateur, utilisée pour l'initialisation MTpush que le développeur autorise le navigateur à exécuter. Les développeurs doivent s'assurer que tous les utilisateurs pouvant appeler et obtenir ces données sont des utilisateurs légitimes.
Structure de données d'initialisation
interface MTInitInfo {
website_push_id: string;
code: number;
master_secret: string;
passwd: string;
pull: number;
regid: string;
sess: string;
tagalias: number;
uid: number;
vapid_pubkey: string;
}
type dataType = {
code: number,
content: string,
message: string,
};
interface InitType {
appkey: string; // L'appkey de l'application enregistrée sur la plateforme EngageLab par le développeur, obligatoire
user_str: string; // Identifiant unique de l'utilisateur, obligatoire
swUrl?: string; // Par défaut "/sw.min." + sdkEnv.version + ".js"
debugMode?: boolean; // Par défaut false
webSocketUrl?: string; // Si non fourni, baseUrl sera utilisé
fail?: (data: dataType | undefined) => void; // Callback en cas d'échec de l'initialisation
success?: (data: dataType | undefined) => void; // Callback en cas de succès de l'initialisation
webPushcallback?: def;
canGetInfo?: (d: MTInitInfo) => void;
custom?: (Callback: () => void) => void; // Callback pour disponibilité de l'invite personnalisée, appelez Callback après l'opération pour appliquer
maCompletion?: (code: number, msg: string) => void; // Callback pour la fin de l'initialisation ma-sdk
/**
* Lien de redirection lors du clic sur une notification, priorité : URL définie lors de l'envoi de la notification -> InitType.openUrl -> domaine de la page intégrée
* Pour le navigateur Safari, les messages délivrés via le canal système nécessitent un traitement supplémentaire : définissez window.MTpushInterfaceTempData = { openUrl: 'https://example.com' } avant de charger le SDK
*/
openUrl?: string;
/**
* Faut-il encoder swUrl
* Scénario d'utilisation :
* Si swUrl contient des caractères spéciaux comme @ et que le serveur restreint l'accès à cette ressource URL, cela peut entraîner l'échec de l'enregistrement du Service Worker ;
* Un mécanisme de réenregistrement du Service Worker est nécessaire, et swUrl doit être encodé lors des tentatives.
*/
encodeSwUrl?: boolean;
}
Un seul service worker peut être enregistré dans le même scope. Si une erreur similaire à "Failed to execute 'subscribe' on 'PushManager': Subscription failed - no active Service Worker" survient lors d'une initialisation réussie, veuillez vérifier les conflits éventuels avec d'autres service workers. Vous devrez peut-être fusionner les service workers ou résoudre le scope du service worker.
Initialisation du SDK
Description de l'interface
Initialiser l'interface.
window.MTpushInterface.init(Object:InitType)
Description des paramètres
- Pour plus de détails, voir [Description InitType](/zh_CN/docs/web-push/sdk/web-sdk-api#Initialize data structure).
- Description des données de l'objet de callback :
| Nom du paramètre | Type de paramètre | Description du paramètre |
|---|---|---|
| code | number | code de retour, 0 signifie succès, autres échecs, voir code d'erreur |
| message | string | description du résultat |
| content | string | Message d'échec de retour lors de l'échec de l'enregistrement 1003 |
Exemple d'appel
MTpushInterface.init({
appkey: "xxx",
user_str: "adminDemo",
fail(data) {
console.log("Échec de la création du push en ligne", data);
},
success(data) {
console.log("Push en ligne créé avec succès", data);
},
webPushcallback(code, tip) {
console.log("Le code d'état et l'indication reçus par l'utilisateur", code, tip);
},
//swUrl?: string; //par défaut "/sw.min." + sdkEnv.version + ".js"
canGetInfo(d) {
//À ce moment, vous pouvez obtenir le RegId ou toutes les données dans d
console.log("Obtenir RegId", MTpushInterface.getRegistrationID(), d);
// MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "swefgwwefwfwfwf" });
},
custom: (reqPermission) => {
//Lors de l'utilisation d'une configuration d'invite personnalisée, vous devez appeler reqPermission pour demander et configurer les autorisations. Obtenez la fonction de demande d'autorisation dans le callback custom et appelez directement reqPermission au moment opportun pour demander les autorisations de notification.
document.getElementById("xx")?.addEventListener("click", reqPermission); },
});
Obtenir RegistrationID
Description de l'interface
Appelez cette API pour obtenir le RegistrationID correspondant au compte actuel. La valeur correspondante n'est renvoyée qu'après la réussite de la signature d'initialisation, sinon une chaîne vide est renvoyée. Cette méthode doit être appelée après le déclenchement du callback canGetInfo.
window.MTpushInterface.getRegistrationID()
Exemple d'appel
var rid = window.MTpushInterface.getRegistrationID();
Arrêter le push
Appelez cette API pour déconnecter la connexion persistante push établie avec l'arrière-plan et arrêter de recevoir des messages push.
window.MTpushInterface.mtPush.stopPush()
Surveillance des messages push
Description de l'interface
Il est recommandé d'appeler l'écouteur de messages avant l'initialisation.
window.MTpushInterface.onMsgReceive(fn)
Description des paramètres
| Nom du paramètre | Type de paramètre | Description du paramètre |
|---|---|---|
| fn | function | Fonction de réception et de traitement des messages |
Exemple d'appel
window.MTpushInterface.onMsgReceive(function (res) {
if(res.type===0){
// res.data.messages[]
// res.data.messages[].msg_id
// res.data.messages[].title
// res.data.messages[].content
// res.data.messages[].extras
}else{
// res.data.title
}
});
Données retournées
| Nom du paramètre | Type de paramètre | Description du paramètre |
|---|---|---|
| type | number | |
| data | Object | contenu du message |
Tableau de messages du canal EngageLab (messages)
| Nom du paramètre | Type de paramètre | Description du paramètre |
|---|---|---|
| msg_id | string | ID du message |
| title | string | Titre du message |
| content | string | Contenu du message |
| extras | Object | Champs supplémentaires du message |
Données de message du canal système
Prend en charge l'interface w3c NotificationOptions, voir mdn web docs pour plus de détails.
Vérifier l'état du service push
window.MTpushInterface.getPushAuthority()
La structure de données retournée est la suivante :
{
mtPush: {
code:1, //1 succès, -1 en initialisation, 0 échec
msg:'success'
},
webPush: {
code:1, // 0 webpush non disponible (le navigateur ne le supporte pas) 1 disponible 2 autorisation désactivée 3 autorisation non confirmée
msg:'success'
}
}
- Codes d'erreur de l'objet WebPush :
| code | msg | Remarques |
|---|---|---|
| 0 | Le navigateur ne prend pas en charge l'API Notifications | Le navigateur ne prend pas en charge l'API Notifications |
| 1 | Autorisations de notification disponibles, abonnement au message réussi. | Autorisations de notification disponibles, abonnement réussi |
| 2 | Autorisations de notification désactivées, abonnement au message échoué. | Autorisations de notification désactivées, abonnement échoué |
| 3 | Autorisations de notification non confirmées, abonnement non effectué. | Autorisations de notification non confirmées, abonnement non effectué |
| -1 | Le navigateur ne prend pas en charge Service Worker. | Le navigateur ne prend pas en charge Service Worker |
| -2 | Service Worker ne prend pas en charge HTTP. | Service Worker ne prend pas en charge le protocole HTTP |
| -3 | Échec de l'enregistrement du Service Worker. | Échec de l'enregistrement du Service Worker |
| -4 | Autorisation de notification disponible, mais abonnement au message échoué. | Autorisation disponible, mais abonnement échoué |
| -5 | L'abonnement a été annulé | Abonnement annulé |
Obtenir l'autorisation de notification du navigateur
window.MTpushInterface.getWebPermission()
Description des paramètres de retour
- granted : disponible
- denied : désactivé
- default: autorisation non confirmée
Rapporter des données de message personnalisé
Si vous avez besoin de faire des statistiques sur les messages personnalisés, veuillez utiliser l'interface de rapport personnalisé pour signaler les données.
window.MTpushInterface.customClickReport('msg_id'); // msg_id est le msg_id du message personnalisé
Surveillance de la déconnexion
Description de l'interface
Si une déconnexion survient après une initialisation réussie, le SDK tentera automatiquement de se reconnecter et de signer. Il est recommandé d'appeler cet écouteur d'événement avant l'initialisation, puis de réinitialiser après réception de cet événement.
window.MTpushInterface.mtPush.onDisconnect(fn)
Exemple d'appel
window.MTpushInterface.mtPush.onDisconnect(function () {
});
Annuler l'abonnement du navigateur
Se désabonner des notifications. Cette méthode peut être utilisée lorsque vous ne souhaitez plus recevoir de notifications lors de la déconnexion d'un compte ou lorsque le niveau de confidentialité de certains comptes est élevé.
MTpushInterface.unSubscribe();
Définir TagsAlias
window.MTpushInterface.setTagsAlias({})
MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });
Description des paramètres
| Nom du paramètre | Type de paramètre | Description du paramètre |
|---|---|---|
| tags | string[] | Obligatoire, longueur maximale du tableau 1000, chaque élément max 40 caractères |
| alias | string | Obligatoire, max 40 caractères |
Description de l'interface
Les développeurs peuvent définir et supprimer des tags sous un alias spécifique via cette interface. Cette interface applique une logique de superposition. Si la notification est définie sur une chaîne vide, les tags existants peuvent être supprimés.
Affichage multiple des invites de catégorie
window.MTpushInterface.promptPushCategories();
Description de l'interface
Après l'abonnement de l'utilisateur aux notifications push, les développeurs peuvent afficher plusieurs fois les invites de catégorie selon les besoins. Cela doit être appelé après l'initialisation du SDK.
Callback d'affichage des messages push
Description de l'interface
Il est recommandé d'appeler l'écouteur de messages avant l'initialisation.
Exemple d'appel
window.MTpushInterface.onMsgDisplay((msgData) => {});
Description des paramètres
Description du paramètre de callback de notification msgData :
{
title: string;
content: string;
msg_id: string;
ntf_or_msg: number;
engagelab_appkey: string;
engagelab_passwd: string;
engagelab_uid: string;
engagelab_url: string;
type: string; // 0 : message du canal EngageLab 1 : message du canal système
}
Description du paramètre de callback de message in-app msgData :
{
title: string;
content: string;
msg_id: string;
ntf_or_msg: number;
type: string;
}
Remarque :
En mode édition HTML pour les messages in-app, les paramètres de callback
titleetcontentsont des chaînes vides.Les messages délivrés via le canal système dans le navigateur Safari ne peuvent pas recevoir de callback d'affichage.
Callback de clic sur message push
Description de l'interface
Il est recommandé d'appeler l'écouteur de messages avant l'initialisation.
Exemple d'appel
window.MTpushInterface.onMsgClick((msgData) => {});
Description des paramètres
Description du paramètre de callback de notification msgData :
{
title: string;
content: string;
msg_id: string;
ntf_or_msg: number;
engagelab_appkey: string;
engagelab_passwd: string;
engagelab_uid: string;
engagelab_url: string;
position: string; // Position du clic, 'msgBody' | ID du bouton
type: string; // 0 : message du canal EngageLab 1 : message du canal système
}
Description du paramètre de callback de message in-app msgData :
{
title: string;
content: string;
msg_id: string;
ntf_or_msg: number;
position: 'msgBody' | 'mainBtn' | 'subBtn' | 'closeBtn';
type: string;
}
Remarque :
- En mode édition HTML pour les messages in-app, la valeur de
positionest déterminée par le développeur, et les paramètres de callbacktitleetcontentsont des chaînes vides.- Les messages délivrés via le canal système dans le navigateur Safari ne peuvent pas recevoir de callback de clic.
Code d'erreur
| code | message | Remarques |
|---|---|---|
| 0 | success | appel réussi |
| 1000 | unknown error | erreur inconnue |
| 1001 | initing , please try again later | initialisation en cours, veuillez réessayer plus tard |
| 1002 | invalid config | erreur de configuration initiale |
| 1003 | init failed | échec de l'initialisation, voir la console pour plus de détails |
| 1004 | init timeout | délai d'initialisation dépassé |
| 1005 | network error | erreur réseau, pas de réseau ou impossible de se connecter au websocket |
| 1006 | failed to get baseUrl and reportUrl | la requête API get-webaddr a échoué, voir le champ content du callback pour plus de détails |
| 1007 | authentication failed | authentification échouée, voir le champ content du callback pour plus de détails |

