Créer une API push

Poussez une notification ou un message vers un seul appareil ou une liste d'appareils. Le contenu envoyé ne peut être qu'un objet push représenté en JSON.

Limites de fréquence des requêtes

Notre API impose des limites de fréquence d'appel afin de garantir la stabilité et l'équité du service. Les limites QPS (requêtes par seconde) pour chaque AppKey sont les suivantes :

• Limite standard : 500 requêtes maximum par seconde.
• Limite avancée : Si vous êtes abonné à notre offre payante et que votre AppKey payant nécessite une limite QPS plus élevée, veuillez contacter notre équipe commerciale : Sales@engagelab.com.

Méthode de requête

POST

Adresse d'appel

L'adresse du service d'interface correspond point à point au point d'accès sélectionné du centre de données. Veuillez sélectionner l'adresse d'appel correspondant au point d'accès de service de votre application.

Actuellement, EngageLab a déployé et prend en charge deux points d'accès de centres de données, et les données entre différents points d'accès de service sont totalement isolées. Vous pouvez sélectionner l'adresse d'appel en fonction du point d'accès du centre de données choisi lors de la création du produit.

              
              POST v4/push

            

Validation de l'appel

Pour plus d'informations, consultez la vue d'ensemble de l'API REST dans la description de la Méthode d'authentification.

Exemple de requête

En-tête de requête

              
              > POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==

            

Corps de la requête

              
              {
    "from": "push",
    "to": "all",
    "body": {
        "platform": "all",
        "notification": {
            "alert" :"Hello, Push!",
            "android": {
                "alert": "Hi, Push!",
                "title": "Envoyer à Android",
                "builder_id": 1,
                "extras": {
                    "newsid": 321
                }
            },
            "ios": {
                "alert": "Hi, MTPush!",
                "sound": "default",
                "badge": "+1",
                "extras": {
                    "newsid": 321
                }
            }
        },
        "options": {
            "time_to_live": 60,
            "apns_production": false
        }
    },
    "request_id": "12345678",
    "custom_args":{
             "Engagelab": "push to you"
    }
}

            

Paramètres de la requête

La structure des paramètres du push, comme détaillé dans le tableau suivant :

from

Expéditeur du service actuel, de type String, champ optionnel.

Exemple de requête

              
              {
    "from":"push"
}

            

to

Objet Appareil Push, qui indique la liste des appareils vers lesquels un push peut être envoyé. Pour confirmer l'objet appareil push, App Push propose plusieurs méthodes, telles que : alias, tag, registration ID, sous-groupe, diffusion, etc.

Cible de push

Il existe plusieurs façons de choisir un équipement en dehors de la diffusion, comme suit :

Exemple

• Push vers tous (diffusion) :

              
              {
  "to": "all"
}

            

• Push vers plusieurs tags (si l'un des tags est satisfait) : à Shenzhen, Guangzhou ou Pékin

              
              {
    "to":{
        "tag":[
            "Shenzhen",
            "Guangzhou",
            "Beijing"
        ]
    }
}

            

• Push vers plusieurs tags (doit être dans la plage de plusieurs tags en même temps) : à Shenzhen et "femme"

              
              {
    "to":{
        "tag_and":[
            "Shenzhen",
            "female"
        ]
    }
}

            

• Push vers plusieurs alias :

              
              {
    "to":{
        "alias":[
            "4314",
            "892",
            "4531"
        ]
    }
}

            

• Push vers plusieurs IDs d'inscription :

              
              {
  "to": {
    "registration_id": [
      "4312kjklfds2",
      "8914afd2",
      "45fdsa31"
    ]
  }
}

            

• Peut être poussé simultanément vers plusieurs types de cibles : à Shenzhen ou Guangzhou et sont "femmes" "membres"

              
              {
    "to":{
        "tag":[
            "Shenzhen",
            "Guangzhou"
        ],
        "tag_and":[
            "female",
            "members"
        ]
    }
}

            

• Push d'un message d'activité en temps réel

              
                {
      "to": {
          "live_activity_id": "LiveActivity-1"
      }
  }

            

Push vers un ID de segmentation utilisateur :

              
              {
  "to": {
    "seg": {
      "id":"segid"
    }
  }
}

            

Body

Corps de la requête d'envoi. Les champs pris en charge sont les suivants :

Plateforme

MTPush prend actuellement en charge le push pour les plateformes Android, iOS et HarmonyOS. Les mots-clés sont : "android", "ios", "hmos".

Push vers toutes les plateformes :

              
              { "platform" : "all" }

            

Désignation de plateformes spécifiques :

              
              {
  "platform": [
    "android",
    "ios",
    "hmos"
  ]
}

            

Notification

L'objet "Notification", qui est l'un des objets de contenu d'une push (l'autre étant "Message"), est envoyé au client en tant que "Notification".

Alert

La propriété "alert" à cet emplacement (directement sous l'objet notification) est une définition raccourcie, et si le message d'alerte est identique sur toutes les plateformes, l'alerte peut ne pas être définie sous la plateforme, et cette valeur primera. Si une définition est présente pour chaque plateforme, elle la remplacera.

              
              {
  "notification" : {
    "alert" : "Hello, Push!"
  }
}

            

L'objet notification défini ci-dessus sera envoyé vers plusieurs plateformes spécifiées par "platform" et toutes auront le même message d'alerte.

Android

Les notifications sur la plateforme Android sont affichées par le SDK MTPush selon des styles spécifiques de barre de notification. Les champs pris en charge sont les suivants :

              
              {
    "notification": {
        "android": {
            "alert": "hello, MTPush!",
            "title": "Test push",
            "builder_id": 3,
            "style": 1,
            "big_text": "contenu grand texte",
            "inbox": Objet JSON,
            "big_pic_path": "url image",
            "priority": 0,
            "category": "catégorie str",
            "large_icon": "http://pushapi-sgp.engagelab.comlargeIcon.jpg",
            "small_icon": "http://www.small.com/small_icon.jpg",
            "intent": {
                "url": "intent:#Intent;component=push.pushapi-sgp.engagelab.com/com.example.mtpushdemo.SettingActivity;end"
            },
            "extras": {
                "news_id": 134,
                "my_key": "a value"
            }
        }
    }
}

            

iOS

Notifications APNs sur la plateforme iOS.

Le contenu de la notification est envoyé par l'agent MTPush au serveur Apple APNs et est présenté sur l'appareil iOS sous forme de notification système.

Le contenu de la notification est conforme aux spécifications APNs et prend en charge les champs suivants :

Exemple d'envoi côté serveur :

              
              {
    "notification": {
        "ios": {
            "alert": "hello, Push!",
            "sound": "sound.caf",
            "badge": 1,
            "extras": {
                "news_id": 134,
                "my_key": "a value"
            }
        }
    }
}

            

Message reçu par le client :

              
              {
  "_j_msgid" = 813843507;
  aps =     {
  alert = "hello,Push!";
  badge = 1;
  sound = "sound.caf";
};
"my_key" = "a value";
"news_id" = 134;
}

            

hmos

Les notifications sur la plateforme HarmonyOS sont affichées par le SDK MTPush selon les styles de la barre de notification. Les champs pris en charge sont les suivants :

Exemple :

              
              {
  "notification": {
    "hmos": {
      "alert": "Hi, MTPush!",
      "title": "",
      "category": "",
      "intent": {"url": ""},
      "badge_add_num": 1,
      "test_message": true,
      "receipt_id": "",
      "extras": {},
      "style": 0,
      "inbox_content": [],
      "push_type": 0,
      "extra_data": "",
      "display_foreground": "1"
    }
  }
}

            

Message

Messages in-app. Également appelés : messages personnalisés, messages pass-through.

• Cette partie n'est pas affichée dans la barre de notification, le SDK MTPush reçoit le contenu du message et le transmet à l'application.
• iOS obtient cette partie dans un canal de message in-app push (pas APNS) avec l'application au premier plan.

Les champs pris en charge sont les suivants :

Exemple :

              
              {
  "message": {
    "msg_content": "Hi,Push",
    "content_type": "text",
    "title": "msg",
    "extras": {
      "key": "value"
    }
  }
}

            

Live_activity

Remarque : Les messages d'activité en temps réel nécessitent l'utilisation d'un certificat iOS P8, qui correspond à la sélection de « Configuration d'authentification par token » dans les paramètres de méthode d'authentification iOS du WebPortal.

Le corps du contenu des messages d'activité en temps réel comprend les informations de champ suivantes :

iOS JSON Object

iOS alert JSON Object

• Les messages d'activité en temps réel iOS pour Engagelab Push sont transférés aux serveurs Apple. Apple exige que les données de mise à jour dynamique pour les messages d'activité en temps réel (ActivityKit) ne dépassent pas 4096 octets.
• Engagelab Push, en raison des exigences de reconditionnement et en tenant compte de la redondance de sécurité, stipule que la longueur totale dans les paramètres "live_activity" pour "iOS" : { } et le contenu entre les accolades ne doit pas dépasser 3584 octets. JPush utilise l'encodage UTF-8, ce qui signifie qu'un caractère chinois occupe 3 octets.

Exemple de push d'activité en temps réel

Le attributes-type et le live_activity_id utilisés pour les activités en temps réel sont rapportés depuis le SDK développeur. Avant d'utiliser les activités en temps réel, le push-to-start token et le update-token de l'appareil doivent être rapportés. Pour les procédures détaillées, référez-vous aux instructions du fabricant Apple sur les activités en temps réel.

• Créer

  { "from": "push", "to": { "registration_id": [ "161a3797c816b134042" ] }, "body": { "platform": "ios", "live_activity": { "ios": { "event": "start", "content-state": { "eventStr": "hello", "eventTime":1685952000 }, "attributes": { "name": "1", "number": 2, "tag": "mytag" }, "alert": { "title": "hello", "body": "welcome" }, "attributes-type": "my_la_type", "relevance-score": 100, "apns-priority": 100 } } }, "request_id": "12345678", "custom_args": "12345678" }

                
                {
      "from": "push",
     "to": {
          "registration_id": [
              "161a3797c816b134042"
          ]
      },
      "body": {
          "platform": "ios",
          "live_activity": {
              "ios": {
                  "event": "start",
                  "content-state": {
                      "eventStr": "hello",
                      "eventTime":1685952000
                  },
                  "attributes": {
                      "name": "1",
                      "number": 2,
                      "tag": "mytag"
                  },
                  "alert": {
                      "title": "hello",
                      "body": "welcome"
                  },
                  "attributes-type": "my_la_type",
                  "relevance-score": 100,
                  "apns-priority": 100
              }
          }
      },
      "request_id": "12345678",
      "custom_args": "12345678"
  }
  
              

  Afficher ce bloc de code dans la fenêtre flottante

• Mettre à jour

  { "from": "push", "to": { "live_activity_id": "my_la_id" }, "body": { "platform": "ios", "live_activity": { "ios": { "event": "update", "content-state": { "eventStr": "test_live", "eventTime": 198 }, "alert": { "title": "123411", "body": "123411" } } } }, "request_id": "12345678", "custom_args": "12345678" }

                
                {
     "from": "push",
     "to": {
           "live_activity_id": "my_la_id"
      },
      "body": {
          "platform": "ios",
          "live_activity": {
              "ios": {
                  "event": "update",
                  "content-state": {
                      "eventStr": "test_live",
                      "eventTime": 198
                  },
  
                  "alert": {
                      "title": "123411",
                      "body": "123411"
                  }
              }
          }
      },
      "request_id": "12345678",
      "custom_args": "12345678"
  }
  
              

  Afficher ce bloc de code dans la fenêtre flottante

Voip

Fonction iOS VOIP. Ce type ne prend pas en charge la coexistence avec d'autres types de messages iOS. Référez-vous à la structure des paramètres de requête :

              
              { 
    "from": "push", 
    "to": { 
        "registration_id": [ "1a0018970a91da03de5" ] 
    }, 
    "request_id": "12345", 
    "custom_args": "12345", 
    "body": { 
        "platform": "ios", 
        "voip": { 
            "key": "value // Toute paire clé/valeur personnalisée qui sera transmise à l'APP" 
        } 
    } 
}

            

Options

Les options actuelles de notification push comprennent les éléments suivants :

Multi_language

Ce champ est destiné à la fonctionnalité de push multilingue du service EngageLab Push. Il vous permet d'envoyer un contenu de notification personnalisé aux utilisateurs dans différentes langues. En spécifiant plusieurs langues avec leur contenu de message, titres et sous-titres iOS correspondants dans la requête push, vous pouvez envoyer des notifications push appropriées basées sur les paramètres de langue de l'utilisateur.

Paramètres de requête

• Remarque HarmonyOS : Lors de l'utilisation de HarmonyOS, utilisez third_party_channel.hmos.distribution_new. Il n'est pas affecté par la configuration globale.

Exemple de requête

              
                 HTTP Request Method: POST
   Request URL: /v4/grouppush or /v4/push
   Request Data Format: JSON
   Exemple de requête :
   {
    "options": {
      "multi_language": {
        "en": {
          "content": "",
          "title": "",
          "ios_subtitle": ""
        }
      }
    }
   }

            

Exemple de réponse

              
              Réponse réussie :
{
   
}

            

              
              
Réponse échouée :
{   
    "code": 400,  
    "data": "",
  "message": "Message d'erreur"
}   

            

Third_party_channel

Ce champ est utilisé pour remplir les informations personnalisées du canal fabricant Android, la clé prend en charge ces canaux fabricants : xiaomi, huawei, meizu, oppo, vivo, fcm, honor, hmos. Un ou plusieurs d'entre eux peuvent exister en même temps, la CLÉ de chaque type de fabricant peut actuellement contenir les options suivantes :

Paramètres de requête

Pour unifier les stratégies multi-canaux fabricants et simplifier la logique de configuration, la méthode de configuration du champ distribution_new est ajustée comme suit. Vos configurations héritées au niveau fabricant resteront effectives, mais il est recommandé de migrer progressivement vers les configurations globales pour éviter les risques de compatibilité futurs. (Les nouvelles règles entreront en vigueur à partir du 2025.04.03) :

• Priorité de configuration (Nouvelles règles)
  • Première priorité : Configuration globale third_party_channel.distribution_new (Nouvelle méthode recommandée)
    Exemple : "distribution_new": "pns_mtpush"
  • Deuxième priorité : Configuration au niveau fabricant third_party_channel.{vendor_key}.distribution_new (Méthode compatible héritée)
    Ne prend effet que lorsque la configuration globale n'est pas définie
  • Aucune configuration : stratégie par défaut : pns_mtpush

Exemple de requête

              
              {
    "third_party_channel": {
        "distribution_new": "pns_mtpush",
        "xiaomi": {
            "channel_id": "*******",
            "small_icon_uri": "http://f6.market.xiaomi.com/download/MiPass/x/x.png",
            "small_icon_color": "#ABCDEF"
        },
        "huawei": {
            "importance": "NORMAL",
            "small_icon_uri": "https://xx.com/xx.jpg",
            "only_use_vendor_style": true
        },
        "oppo": {
            "channel_id": "*******",
            "big_picture_id": "",
            "small_picture_id": ""
        },
        "vivo": {
            "pushMode": 0
        },
        "hmos": {
            "distribution_new": "pns_mtpush"
        }
    }
}

            

Request_id

ID de requête, un champ optionnel défini par le client. Utilisé par le client pour identifier quelle requête est en cours et retourné dans la réponse.

Exemple de requête

              
              {
      "request_id":"12345678"
}

            

Exemple de retour

              
              {
    "msg_id": "1225764",
    "request_id": "12345678"
}

            

Custom_args

Défini par le client, champ optionnel qui n'est pas retourné dans la réponse et est retourné dans le callback.

Exemple de requête

              
              {
  "custom_args":{
    "args1": "args1"
  }
}

            

Paramètres de retour

Retour réussi

              
              < HTTP/1.1 200 OK
< Content-Type: application/json
{"request_id":"18","msg_id":"1828256757"}

            

Retour en échec

Le code de statut http est 4xx ou 5xx et le corps de la réponse contient les champs suivants :

              
              {
    "error":{
    "code": 3002,
    "message": "Push.template field must be set correctly when type is template"
    }
}

            

Retours d'appel

Code de statut HTTP

Document de référence : HTTP-Status-Code

Code d'erreur

Limitations de push

Code multi-langue