Push-API erstellen

Senden Sie eine Benachrichtigung oder eine Nachricht an ein einzelnes Gerät oder eine Geräteliste. Der übermittelte Inhalt kann nur ein per JSON dargestelltes Push-Objekt sein.

Anfrage-Limits

Unsere API begrenzt die Aufrufhäufigkeit, um Stabilität und Fairness des Dienstes zu gewährleisten. Die QPS-Limits (Queries Per Second) pro AppKey lauten:

• Standard-Limit: Maximal 500 Anfragen pro Sekunde.
• Erweitertes Limit: Wenn Sie unseren kostenpflichtigen Tarif nutzen und Ihr kostenpflichtiger AppKey ein höheres QPS-Limit benötigt, wenden Sie sich bitte an unser Vertriebsteam: Sales@engagelab.com.

Anfragemethode

POST

Aufrufadresse

Die Schnittstellen-Serviceadresse steht in eins-zu-eins-Beziehung zum gewählten Zugangspunkt des Rechenzentrums. Bitte verwenden Sie die Aufrufadresse, die zum Zugangspunkt Ihrer Anwendung passt.

Derzeit betreibt EngageLab zwei Zugangspunkte in Rechenzentren; die Daten zwischen verschiedenen Service-Zugangspunkten sind vollständig isoliert. Sie können die Aufrufadresse entsprechend dem beim Anlegen des Produkts gewählten Rechenzentrum-Zugangspunkt wählen.

              
              
POST v4/push

            

Aufrufvalidierung

Weitere Informationen finden Sie in der REST-API-Übersicht unter Authentifizierungsmethode.

Anfragebeispiel

Anfrage-Header

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

            

Anfrage-Body

              
              {
    "from": "push",
    "to": "all",
    "body": {
        "platform": "all",
        "notification": {
            "alert" :"Hello, Push!",
            "android": {
                "alert": "Hi, Push!",
                "title": "Send to 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"
    }
}

            

Anfrageparameter

Die Parameterstruktur des Pushs ist in der folgenden Tabelle beschrieben:

from

Aktueller Dienst-Absender, Typ String, optionales Feld.

Anfragebeispiel

              
              {
    "from":"push"
}

            

to

Push-Geräteobjekt: Liste der Geräte, an die gesendet werden kann. Zur Festlegung des Ziels stellt App Push verschiedene Wege bereit, z. B. Alias, Tag, Registrierungs-ID, Untergruppe, Broadcast usw.

Push-Ziel

Neben Broadcast gibt es folgende Möglichkeiten:

Beispiel

• Push an alle (Broadcast):

              
              {
  "to": "all",
}

            

• Push an mehrere Tags (mindestens eines der Tags): in Shenzhen, Guangzhou oder Peking

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

            

• Push an mehrere Tags (alle Tags gleichzeitig): in Shenzhen und „female“

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

            

• Push an mehrere Aliase:

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

            

• Push an mehrere Registrierungs-IDs:

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

            

• Mehrere Zieltypen gleichzeitig: in Shenzhen oder Guangzhou und gleichzeitig „female“ und „members“

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

            

• Live-Activity-Nachricht senden

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

            

Push an Nutzersegment-ID:

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

            

Body

Anfrage-Body. Unterstützte Felder:

Plattform

MTPush unterstützt Push für Android, iOS und HarmonyOS. Schlüsselwörter: "android", "ios", "hmos".

Push an alle Plattformen:

              
              { "platform" : "all" }

            

Bestimmte Plattformen auswählen:

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

            

Notification

Das Objekt „Notification“ ist einer der Inhalts-Entity-Typen eines Pushs (der andere ist „Message“) und wird dem Client als Benachrichtigung zugestellt.

Alert

Die Eigenschaft alert auf dieser Ebene (direkt unter dem Notification-Objekt) ist eine Kurzform: Ist der Alert auf allen Plattformen gleich, können Sie alert nicht pro Plattform setzen; dieser Wert gilt. Gibt es plattformspezifische Definitionen, überschreiben diese den Wert hier.

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

            

Das oben definierte Notification-Objekt wird an alle in platform genannten Plattformen mit derselben Alert-Nachricht gesendet.

Android

Benachrichtigungen unter Android werden vom MTPush SDK gemäß den Benachrichtigungsleisten-Stilen angezeigt. Unterstützte Felder:

              
              {
    "notification": {
        "android": {
            "alert": "hello, MTPush!",
            "title": "Push test",
            "builder_id": 3,
            "style": 1,
            "big_text": "big text content",
            "inbox":JSONObject,
            "big_pic_path": "picture url",
            "priority": 0,
            "category": "category 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

APNs-Benachrichtigungen auf iOS.

Der Inhalt wird vom MTPush-Proxy an Apple APNs gesendet und erscheint auf dem Gerät als Systembenachrichtigung.

Der Inhalt entspricht der APNs-Spezifikation; unterstützte Felder:

Beispiel serverseitige Zustellung:

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

            

Vom Client empfangene Nachricht:

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

            

hmos

HarmonyOS-Benachrichtigungen werden vom MTPush SDK gemäß Benachrichtigungsleisten-Stilen angezeigt. Unterstützte Felder:

Beispiel:

              
              {
  "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

In-App-Nachrichten (auch: benutzerdefinierte oder durchgereichte Nachrichten).

• Werden nicht in der Benachrichtigungsleiste angezeigt; das MTPush SDK übergibt den Inhalt an die App.
• iOS erhält diesen Teil über den In-App-Push-Kanal (nicht APNS), wenn die App im Vordergrund ist.

Unterstützte Felder:

Beispiel:

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

            

Live_activity

Hinweis: Live-Activity-Nachrichten erfordern ein iOS-P8-Zertifikat; in den iOS-Authentifizierungseinstellungen im Web-Portal wählen Sie „Token Authentication Configuration“.

Der Inhalt einer Live-Activity-Nachricht umfasst folgende Felder:

iOS JSON-Objekt {#ios-json-object}

iOS alert JSON-Objekt {#ios-alert-json-object}

• Live-Activity-Nachrichten von Engagelab Push werden an Apple-Server weitergeleitet. Dynamische Update-Daten (ActivityKit) dürfen 4096 Byte nicht überschreiten.
• Engagelab Push begrenzt aus Repackaging- und Sicherheitsgründen die Gesamtlänge der Parameter unter live_activity für "ios": { } inkl. Inhalt auf 3584 Byte. JPush/MTPush nutzt UTF-8 (ein chinesisches Zeichen = 3 Byte).

Beispiel Live-Activity-Push

attributes-type und live_activity_id kommen aus dem Entwickler-SDK. Vor Nutzung müssen Start- und Update-Token gemeldet werden. Ablauf siehe Apple: Live Activities mit Push.

• Erstellen

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

  Diesen Codeblock im schwebenden Fenster anzeigen

• Aktualisieren

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

  Diesen Codeblock im schwebenden Fenster anzeigen

Voip

iOS-VoIP. Dieser Typ darf nicht mit anderen iOS-Nachrichtentypen kombiniert werden. Anfragestruktur:

              
              { 
    "from": "push", 
    "to": { 
        "registration_id": [ "1a0018970a91da03de5" ] 
    }, 
    "request_id": "12345", 
    "custom_args": "12345", 
    "body": { 
        "platform": "ios", 
        "voip": { 
            "key": "value // Any custom key/value pair that will be passed to the APP" 
        } 
    } 
}

            

Android VoIP functionality. Android VoIP is configured through options.third_party_channel. Xiaomi, vivo, OPPO, and Honor vendor channels are currently supported. OPPO VoIP is supported only on the China node. Request parameter structure:

              
              {
    "from": "push",
    "to": {
        "registration_id": [
            "1a0018970a91da03de5"
        ]
    },
    "request_id": "12345",
    "custom_args": {
        "call_id": "call-10001"
    },
    "body": {
        "platform": "android",
        "options": {
            "classification": 1,
            "third_party_channel": {
                "xiaomi": {
                    "voip_extraData": "{\"call_id\":\"call-10001\",\"caller\":\"Alice\"}",
                    "channel_id": "voip-channel-id",
                    "callback_id": "callback-10001", // optional
                    "voip_appMessageId": "app-message-10001", // optional
                    "voip_callBackParam": "callback-param-10001", // optional
                    "voip_ttl": 30, // optional
                    "voip_collapseKey": 1 // optional
                },
                "vivo": {
                    "voip_extraData": "{\"call_id\":\"call-10001\",\"caller\":\"Alice\"}",
                    "voip_extensionExpireShow": true, // optional
                    "callback_id": "callback-10001", // optional
                    "voip_appMessageId": "app-message-10001", // optional
                    "voip_callBackParam": "callback-param-10001", // optional
                    "voip_ttl": 30, // optional
                    "voip_collapseKey": 1 // optional
                },
                "oppo": {
                    "voip_extraData": "{\"call_id\":\"call-10001\",\"caller\":\"Alice\"}",
                    "callback_id": "callback-10001", // optional
                    "voip_appMessageId": "app-message-10001", // optional
                    "voip_callBackParam": "callback-param-10001", // optional
                    "voip_ttl": 30, // optional
                    "voip_collapseKey": 1 // optional
                },
                "honor": {
                    "voip_extraData": "{\"call_id\":\"call-10001\",\"caller\":\"Alice\"}",
                    "voip_appMessageId": "app-message-10001", // optional
                    "voip_callBackParam": "callback-param-10001", // optional
                    "voip_ttl": 30, // optional
                    "voip_collapseKey": 1 // optional
                }
            }
        }
    }
}

            

Notes:

• voip_extraData is a string. If JSON data needs to be passed, serialize the JSON object to a string first.
• When setting voip_extraData for the Xiaomi channel, channel_id must also be set.
• OPPO VoIP is supported only on the China node.
• You can pass only the configuration for the vendor channels that your app actually integrates.
• Android VoIP does not require notification.alert and cannot be sent together with message or inappmessage.
• Android VoIP does not use the body.voip field. That field is only used for iOS VoIP.
• Set options.classification = 1.

Options

Aktuelle Push-Optionen:

Mehrsprachiger Push {#multi_language}

Feld für mehrsprachigen Push von EngageLab Push. Sie können pro Nutzersprache angepasste Titel und Texte senden, indem Sie Sprachen und Inhalte in der Anfrage angeben.

Anfrageparameter

• HarmonyOS: Nutzen Sie third_party_channel.hmos.distribution_new; nicht von der globalen Konfiguration betroffen.

Anfragebeispiel

              
              {
  "options": {
    "multi_language": {
      "en": {
        "content": "",
        "title": "",
        "ios_subtitle": ""
      }
    }
  }
}

            

Herstellerkanal (third_party_channel) {#third_party_channel}

Persönliche Einstellungen für Android-Herstellerkanäle. Unterstützte Schlüssel: xiaomi, huawei, meizu, oppo, vivo, fcm, honor, hmos – eine oder mehrere gleichzeitig. Pro Herstellertyp können folgende Optionen gesetzt werden:

Anfrageparameter

Zur Vereinheitlichung der Mehrkanal-Strategie wurde die Konfiguration von distribution_new angepasst. Bestehende herstellerspezifische Einstellungen bleiben gültig; empfohlen ist schrittweise Migration zur globalen Konfiguration (Wirksam ab 2025.04.03):

• Priorität (neue Regeln)
  • Höchste Priorität: global third_party_channel.distribution_new (empfohlen)
    Beispiel: "distribution_new": "pns_mtpush"
  • Zweite Priorität: pro Hersteller third_party_channel.{vendor_key}.distribution_new (Legacy)
    Nur wenn global nicht gesetzt
  • Ohne Konfiguration: Standard pns_mtpush

Anfragebeispiel

              
              {
    "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",
            "template_id": "xiaomi_template_id",
            "template_param": {
                "name": "EngageLab"
            }
        },
        "huawei": {
            "importance": "NORMAL",
            "small_icon_uri": "https://xx.com/xx.jpg"
        },
        "oppo": {
            "channel_id": "*******",
            "big_picture_id": "",
            "small_picture_id": "",
            "private_msg_template_id": "*******",
            "private_title_parameters": {"city": "北京"},
            "private_content_parameters": {"userName": "汤姆", "city": "深圳市"},
            "badge_operation_type": 1
        },
        "vivo": {
            "pushMode": 0,
            "add_badge": true
        },
        "fcm": {
            "distribution_new": "pns_mtpush",
            "priority": "high",
            "notification_as_message": true
        },
        "hmos": {
            "distribution_new": "pns_mtpush"
        }
    }
}

            

Request_id

Optionales, vom Kunden definiertes Request-ID-Feld. Dient der Zuordnung von Anfrage und Antwort.

Anfragebeispiel

              
              {
      "request_id":"12345678"
}

            

Antwortbeispiel

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

            

Custom_args

Vom Kunden definiertes optionales Feld; nicht in der direkten API-Antwort, aber im Callback.

Anfragebeispiel

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

            

Rückgabeparameter

Erfolgreiche Antwort

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

            

Fehlerhafte Antwort

HTTP-Status 4xx oder 5xx; Antwortbody enthält u. a.:

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

            

Antwort des Aufrufs

HTTP-Statuscode

Referenz: HTTP-Status-Code

Fehlercodes {#fehlercodes}

Push-Beschränkungen

Mehrsprachige Sprachcodes