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

            
Afficher ce bloc de code dans la fenêtre flottante
  • 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.

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)
              
              window.MTpushInterface.init(Object:InitType)

            
Afficher ce bloc de code dans la fenêtre flottante

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"); } }); }, });
              
              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");
      }
    });
  },
});

            
Afficher ce bloc de code dans la fenêtre flottante

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()
              
              window.MTpushInterface.getRegistrationID()

            
Afficher ce bloc de code dans la fenêtre flottante

Exemple d'appel

var rid = window.MTpushInterface.getRegistrationID();
              
              var rid = window.MTpushInterface.getRegistrationID();

            
Afficher ce bloc de code dans la fenêtre flottante

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()
              
              window.MTpushInterface.mtPush.stopPush()

            
Afficher ce bloc de code dans la fenêtre flottante

Surveillance des messages push

Description de l'interface

Il est recommandé d'appeler l'écouteur de messages avant l'initialisation.

window.MTpushInterface.onMsgReceive(fn)
              
              window.MTpushInterface.onMsgReceive(fn)

            
Afficher ce bloc de code dans la fenêtre flottante

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 } });
              
              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
   }

});

            
Afficher ce bloc de code dans la fenêtre flottante

Données retournées

Nom du paramètre Type de paramètre Description du paramètre
type number
  • 0 : message du canal EngageLab
  • 1 : message du canal système
  • 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()
                  
                  window.MTpushInterface.getPushAuthority()
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    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' } }
                  
                  {
       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'
       }
    }
    
                
    Afficher ce bloc de code dans la fenêtre flottante
    • 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()
                  
                  window.MTpushInterface.getWebPermission()
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    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é
                  
                  window.MTpushInterface.customDisplayReport('msg_id'); // msg_id est le msg_id du message personnalisé
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    Reporting de clic :

    window.MTpushInterface.customClickReport('msg_id'); // msg_id est le msg_id du message personnalisé
                  
                  window.MTpushInterface.customClickReport('msg_id'); // msg_id est le msg_id du message personnalisé
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    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)
                  
                  window.MTpushInterface.mtPush.onDisconnect(fn)
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    Exemple d'appel

    window.MTpushInterface.mtPush.onDisconnect(function () { });
                  
                  window.MTpushInterface.mtPush.onDisconnect(function () {
    });
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    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();
                  
                  MTpushInterface.unSubscribe();
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    Définir TagsAlias

    window.MTpushInterface.setTagsAlias({})

    MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });
                  
                  MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    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"); });
                  
                  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");
    });
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    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();
                  
                  window.MTpushInterface.promptPushCategories();
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    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) => {});
                  
                  window.MTpushInterface.onMsgDisplay((msgData) => {});
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    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; }
                  
                  {
      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;
    }
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    Description du paramètre de callback de message in-app msgData :

    { title: string; content: string; msg_id: string; ntf_or_msg: number; type: string; }
                  
                  {
      title: string;
      content: string;
      msg_id: string;
      ntf_or_msg: number;
      type: string;
    }
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    Remarque :

    1. En mode édition HTML pour les messages in-app, les paramètres de callback title et content sont des chaînes vides.

    2. 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) => {});
                  
                  window.MTpushInterface.onMsgClick((msgData) => {});
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    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 }
                  
                  {
      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
    }
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    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; }
                  
                  {
      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;
    }
    
                
    Afficher ce bloc de code dans la fenêtre flottante

    Remarque :

    1. En mode édition HTML pour les messages in-app, la valeur de position est déterminée par le développeur, et les paramètres de callback title et content sont des chaînes vides.
    2. 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
    Icon Solid Transparent White Qiyu
    Contactez-nous