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 {
report_url?: string; // Report URL, used for private cloud or custom deployments
baseUrl?: string; // Server domain; when used together with report_url, the private cloud or custom deployment logic is used
userLang?: string; // Defaults to navigator.language and must be a language value supported by the browser
safari_url?: string; // Safari push test field
appkey: string; // AppKey of the application registered on the EngageLab platform, required
user_str: string; // Unique user identifier, required
swUrl?: string; // Default: "/sw" + sdkEnv.prefix
is_temporary?: "n" | "t"; // Default: "n"
debugMode?: boolean; // Default: false
webSocketUrl?: string; // If not provided, baseUrl will be used
fail?: (data: dataType | undefined) => void; // Initialization failure callback
success?: (data: dataType | undefined) => void; // Initialization success callback
webPushcallback?: def;
canGetInfo?: (d: MTInitInfo) => void;
custom?: (Callback: () => void) => void; // Callback for custom prompts; call Callback to request notification permission
maOpen?: boolean; // Whether to enable the ma-sdk module
maChannel?: string; // Channel name used by ma-sdk; default: default-channel
appName?: string; // Website name used by ma-sdk for reporting
userIdentity?: { userId?: string; anonymousId?: string }; // User identity used by ma-sdk
maCompletion?: (code: number, msg: string) => void; // ma-sdk initialization completion callback
openUrl?: string; // Redirect link when clicking a notification
encodeSwUrl?: boolean; // Whether to encode swUrl
regidSearchPath?: string; // Page path for querying Registration ID
}
- Description des paramètres :
- openUrl : URL ouverte au clic sur une notification
- Si aucune URL n'est spécifiée à l'envoi de la notification, cette valeur est utilisée comme lien de redirection ;
- Si le paramètre n'est pas défini, la redirection se fait par défaut vers le domaine d'intégration ;
- En intégration multi-domaines, ce paramètre permet la redirection vers l'URL correspondante ;
- encodeSwUrl : Faut-il encoder swUrl
- À utiliser lorsque swUrl contient des caractères spéciaux (ex. @) et que le serveur restreint l'accès à cette URL, ce qui peut faire échouer l'enregistrement du Service Worker ; ajouter un mécanisme de réenregistrement et encoder swUrl lors des tentatives.
- regidSearchPath : Chemin de la page pour consulter le Registration ID ; par défaut /engagelab/regid. Voir Guide de consultation du Registration ID.
- openUrl : URL ouverte au clic sur une notification
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](/fr_FR/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
const appkey = "your_appkey";
const userStr = "adminDemo";
MTpushInterface.init({
appkey: appkey,
user_str: userStr,
fail(data) {
console.log("Online push setup failed", data);
},
success(data) {
console.log("Online push setup successful", data);
},
webPushcallback(code, tip) {
console.log("Status code and message", code, tip);
},
canGetInfo(data) {
// RegId is available here, and initialization config data can also be read from data.
console.log("Obtained RegId", MTpushInterface.getRegistrationID(), data);
// MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "swefgwwefwfwfwf" });
},
custom: (requestPermission) => {
// For custom prompt settings, call requestPermission during an appropriate user action to request notification permission.
document.getElementById("subscribe")?.addEventListener("click", () => {
if (Notification.permission === "default") {
requestPermission();
} else if (Notification.permission === "denied") {
console.log("Notification permission is denied and cannot be requested");
} else {
console.log("Notification permission has already been granted");
}
});
},
});
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
Reporting des messages personnalisés
Si vous avez besoin de statistiques sur les messages personnalisés, veuillez utiliser les API de reporting personnalisé.
Reporting d'affichage :
window.MTpushInterface.customDisplayReport('msg_id'); // msg_id est le msg_id du message personnalisé
Reporting de clic :
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 des tags et un alias via cette interface. Notez que cette interface utilise une logique d'écrasement : définir une chaîne vide supprimera les tags et alias existants.
Définir la langue des notifications
MTpushInterface.setLan(lan)
MTpushInterface.setLan(lan, (err) => {
alert(err ? "Échec de la définition de la langue des notifications : " + err : "Langue des notifications définie avec succès");
});
Description des paramètres
| Nom du paramètre | Type du paramètre | Description du paramètre |
|---|---|---|
| Paramètre 1 | string | Obligatoire. Paramètre de langue au format ISO 639-1, par exemple "cn" pour le chinois, "en" pour l'anglais et "ja" pour le japonais |
| Paramètre 2 | Function | Callback facultatif. Il est appelé une fois le réglage terminé. Le paramètre err contient les informations d'erreur le cas échéant ; sans err, l'opération a réussi |
Description de l'interface
Les développeurs peuvent utiliser cette API pour définir manuellement la langue des notifications. Une fois le réglage réussi, le SDK enregistre cette langue. Si userLang n'est pas transmis lors de l'initialisation suivante, la langue enregistrée localement est utilisée en priorité.
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 :
{
engagelab_ntf_or_msg: number;
engagelab_appkey: string;
engagelab_passwd: string;
engagelab_uid: number;
engagelab_mesg_type: string;
engagelab_m_str: string;
engagelab_a_str: string;
type: number;
title: string;
content: string;
msg_id: string;
}
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 :
{
engagelab_ntf_or_msg: number;
engagelab_appkey: string;
engagelab_passwd: string;
engagelab_uid: number;
engagelab_mesg_type: string;
engagelab_m_str: string;
engagelab_a_str: string;
type: number;
title: string;
content: string;
msg_id: string;
target_event: string | null;
position: string; // Position du clic, 'msgBody' | ID du bouton
}
Description du paramètre de callback de message in-app msgData :
{
position: 'msgBody' | 'mainBtn' | 'subBtn' | 'closeBtn';
msg_id: number;
title: string;
content: string;
extras: object | null;
ntf_or_msg: number;
strategy: object | null;
target_event: unknown[];
type: number;
icon: 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 |
| 1008 | region restricted | Restriction régionale |










