プッシュAPIの作成

単一デバイスまたはデバイスリストに通知またはメッセージをプッシュします。 プッシュされるコンテンツは、JSONで表されるプッシュオブジェクトのみです。

リクエストレート制限

サービスの安定性と公平性を確保するため、APIには呼び出し頻度の制限が設けられています。各AppKeyのQPS（毎秒クエリ数）制限は以下の通りです：

• 標準制限：1秒あたり最大500リクエスト
• 高度制限：有料プランのサブスクライバーで、有料AppKeyに更高のQPS制限が必要な場合は、営業チームに連絡してください：Sales@engagelab.com。

リクエスト方法

POST

呼び出しアドレス

インターフェースサービスアドレスは、データセンターの選択したアクセスポイントと一対一に対応しています。アプリケーションサービスアクセスポイントに対応する呼び出しアドレスを選択してください。

現在、EngageLabは2つのデータセンターアクセスポイントをデプロイしてサポートしており、異なるサービスアクセスポイント間のデータは完全に分離されています。製品作成時に選択したデータセンターアクセスポイントに応じて、呼び出しアドレスを選択できます。

              
              
POST v4/push

            

呼び出し検証

詳細については、認証方法のREST API概要の説明を参照してください。

リクエスト例

リクエストヘッダー

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

            

リクエストボディ

              
              {
    "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"
    }
}'
> POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==

            

リクエストパラメータ

プッシュのパラメータ構造は、次の表の詳細の通りです：

from

現在のサービス送信者、String型、オプションフィールド。

リクエスト例

              
              {
    "from":"push"
}

            

to

プッシュデバイスオブジェクトは、プッシュを送信できるデバイスのリストを示します。プッシュデバイスオブジェクトを確認するため、App Pushは、エイリアス、タグ、登録ID、サブグループ、ブロードキャストなどのさまざまな方法を提供しています。

プッシュ対象

ブロードキャスト以外に、機器を選択する方法はいくつかあります。以下の通りです：

例

• 全員にプッシュ（ブロードキャスト）：

              
              {
  "to": "all",
}

            

• 複数のタグにプッシュ（いずれかのタグ内に該当する限り）：深圳、広州、北京

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

            

• 複数のタグにプッシュ（複数のタグの範囲内に同時に存在する必要があります）：深圳に在住し、「女性」

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

            

• 複数のエイリアスにプッシュ：

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

            

• 複数の登録IDにプッシュ：

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

            

• 複数のタイプのプッシュ対象を同時に指定してプッシュ：深圳または広州に在住し、「女性」「会員」

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

            

• ライブアクティビティメッセージをプッシュ

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

            

Body

送信リクエストボディ。サポートされているフィールドは以下の通りです：

Platform

MTPushは現在、AndroidおよびiOSプラットフォームのプッシュをサポートしています。キーワードはそれぞれ「android」、「ios」です。

すべてのプラットフォームにプッシュ：

              
              { "platform" : "all" }

            

特定のプッシュプラットフォームの指定：

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

            

Notification

「Notification」オブジェクトは、プッシュのエンティティコンテンツオブジェクトの1つ（もう1つは「Message」）で、「Notification」としてクライアントにプッシュされます。

Alert

この場所（notificationオブジェクトの直下）の「alert」プロパティはショートカット定義であり、プラットフォーム間でalertメッセージが同じ場合、プラットフォームの下でalertを定義しなくても、ここが優先されます。各プラットフォームに定義がある場合は、ここの定義を上書きします。

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

            

上で定義されたnotificationオブジェクトは、「platform」で指定された複数のプラットフォームにプッシュされ、すべて同じnotification alertメッセージを持ちます。

Android

Androidプラットフォームの通知は、MTPush SDKによって特定の通知バースタイルに従って表示されます。サポートされているフィールドは以下の通りです：

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

iOSプラットフォームのAPNs通知。

通知コンテンツはMTPushエージェントによってApple APNsサーバーに送信され、iOSデバイスにシステム通知として表示されます。

通知コンテンツはAPNs仕様を満たしており、以下のフィールドをサポートしています：

サーバー側の配信例：

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

            

クライアントが受信したメッセージ：

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

            

Message

アプリ内メッセージ。カスタムメッセージ、パススルーメッセージとも呼ばれます。

• この部分は通知バーに表示されず、MTPush SDKがメッセージコンテンツを受信してAppに渡します。
• iOSは、アプリがフォアグラウンドにある状態で、プッシュインアプリメッセージチャネル（APNSではない）でこの部分を取得します。

サポートされているフィールドは以下の通りです：

例：

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

            

Live_activity

注意：リアルタイムアクティビティメッセージにはiOS P8証明書の使用が必要で、WebPortalのiOS認証方法設定で「トークン認証設定」を選択することに対応します。

リアルタイムアクティビティメッセージコンテンツ本体には以下のフィールド情報が含まれています：

iOS JSONオブジェクト

iOS alert JSONオブジェクト

• Engagelab PushのiOSリアルタイムアクティビティメッセージはAppleサーバーに転送されます。Appleは、リアルタイムアクティビティメッセージ（ActivityKit）の動的更新データが4096バイトを超えないように要求しています。
• Engagelab Pushは、リパッケージ要件とセキュリティ冗長性を考慮して、「iOS」内の「live_activity」パラメータ内の総長と波括弧内の内容が3584バイトを超えないように規定しています。JPushはUTF-8エンコーディングを使用しているため、1つの漢字は3バイトを占めます。

リアルタイムアクティビティプッシュ例

リアルタイムアクティビティに使用されるattributes-typeとlive_activity_idは開発者SDKから報告されます。リアルタイムアクティビティを使用する前に、デバイスのプッシュ開始トークンと更新トークンを報告する必要があります。詳細な手順については、Appleメーカーのリアルタイムアクティビティの説明を参照してください。

• 作成

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

  このコードブロックはフローティングウィンドウ内に表示されます

• 更新

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

  このコードブロックはフローティングウィンドウ内に表示されます

Voip

iOS VOIP機能。このタイプは他のiOSメッセージタイプとの共存をサポートしていません。リクエストパラメータ構造を参照してください：

              
              { 
    "from": "push", 
    "to": { 
        "registration_id": [ "1a0018970a91da03de5" ] 
    }, 
    "request_id": "12345", 
    "custom_args": "12345", 
    "body": { 
        "platform": "ios", 
        "voip": { 
            "key": "value // APPに渡される任意のカスタムキー/値のペア" 
        } 
    } 
}

            

Options

現在のプッシュ通知オプションには以下が含まれます：

Multi_language

このフィールドは、EngageLab Pushサービスの多言語プッシュ機能

能に使用されます。さまざまな言語のユーザーにカスタマイズされた通知コンテンツを送信できます。プッシュリクエストで複数の言語とそれに対応するメッセージコンテンツ、タイトル、iOSサブタイトルを指定することで、ユーザーの言語設定に基づいて適切なプッシュ通知を送信できます。

リクエストパラメータ

リクエスト例

              
                 HTTPリクエスト方法: POST
   リクエストURL: /v4/grouppushまたは/v4/push
   リクエストデータ形式: JSON
   リクエスト例:
   {
    "options": {
      "multi_language": {
        "en": {
          "content": "",
          "title": "",
          "ios_subtitle": ""
        }
      }
    }
   }

            

リクエスト例

              
              成功レスポンス:
{
   
}

            

              
              
失敗レスポンス:
{   
    "code": 400,  
    "data": "",
  "message": "エラーメッセージ"
}   

            

Third_party_channel

このフィールドはAndroidベンダーチャネルの個別情報を入力するために使用され、キーは7つのAndroidベンダーチャネル（xiaomi、huawei、meizu、oppo、vivo、fcm、honor）のみをサポートしており、そのうちの1つまたは複数を同時に存在させることができます。各ベンダータイプのKEYには現在以下のオプションを含めることができます：

リクエストパラメータ

マルチベンダーチャネル戦略を統一し、構成ロジックを簡素化するため、distribution_newフィールドの構成方法は以下のように調整されました。 従来のベンダーレベルの構成は引き続き有効ですが、将来の互換性リスクを回避するため、段階的にグローバル構成に移行することを推奨します。（新しいルールは2025.04.03から有効になります）：

• 構成優先度（新しいルール）
  • 第一優先： グローバル構成third_party_channel.distribution_new（推奨される新しい方法）
    例："distribution_new": "pns_mtpush"
  • 第二優先： ベンダーレベルの構成third_party_channel.{vendor_key}.distribution_new（従来の互換方法）
    グローバル構成が設定されていない場合にのみ有効になります
  • 無構成： デフォルト戦略：pns_mtpush

リクエスト例

              
              {
    "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": "*******",
            "large_icon": "3653918_5f92b5739ae676f5745bcbf4"
        },
        "vivo": {
            "pushMode": 0
        }
    }
}

            

Request_id

リクエストIDは、顧客定義のオプションフィールドです。クライアントはどのリクエストの応答を返しているかを識別するために使用します。

リクエスト例

              
              {
      "request_id":"12345678"
}

            

戻り例

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

            

Custom_args

顧客定義のオプションフィールドで、応答では返されず、コールバックで返されます。

リクエスト例

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

            

戻りパラメータ

成功した戻り

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

            

戻りに失敗

httpステータスコードは4xxまたは5xxで、応答ボディには以下のフィールドが含まれています：

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

            

呼び出し戻り

HTTPステータスコード

参照ドキュメント：HTTP-ステータスコード

エラーコード

プッシュ制限

多言語コード