Push API v4

  • 単一デバイスまたはデバイスリストに通知またはメッセージをプッシュします。
  • プッシュコンテンツはJSON形式の単一プッシュオブジェクトのみです。
  • ラベル/エイリアス関連の機能については、AppPushAPIを参照してください。

これは最新バージョンのPush APIです。v4バージョンの改良点は以下のとおりです:

  • HTTP Basic Authenticationを使用してアクセスを認可します。これにより、curlやブラウザプラグインなどの一般的なHTTPツールを使用してAPIリクエスト全体を完了できます。
  • プッシュコンテンツはJSON形式です。

Request Rate Limits

サービスの安定性と公平性を確保するため、APIには呼び出し頻度の制限が設けられています。各AppKeyのQPS(Queries Per Second)制限は以下のとおりです:

  • Standard Limit:1秒あたり最大500リクエスト。
  • Advanced Limit:有料プランのサブスクライバーで、有料AppKeyに更高のQPS制限が必要な場合は、営業チームにお問い合わせください:Sales@engagelab.com

Call Validation

詳細については、Authentication methodを参照してください。

Call Address

POST v4/push
              
              POST v4/push

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

Sample Requests

Request header

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

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

Request body

{ "from": "push", "to": "all", "body": { "platform": "web", "notification": { "alert": "Hi,MTPush !",//optional "web": { "alert": "web_push", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } } }, "request_id": "12345678", "custom_args": "business info" }
              
              {
    "from": "push",
    "to": "all",
    "body": {
        "platform": "web",
        "notification": {
            "alert": "Hi,MTPush !",//optional
            "web": {
                "alert": "web_push",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        }
    },
    "request_id": "12345678",
    "custom_args": "business info"
}

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

Request Parameters

プッシュのパラメータ構造は、以下の表に詳細を示します。

Keyword Type Option Description
from String Optional 現在の業務送信元
to String または JSON Object Required 送信対象
body JSON Object Required 送信リクエスト本体
platform String または JSON Array Required プッシュプラットフォーム
notification JSON Object Optional
  • クライアントにプッシュされる通知内容。
  • messageとは同時に存在できず、どちらか一方が必須です。
  • message JSON Object Optional
  • クライアントにプッシュされるメッセージ内容。
  • notificationとは同時に存在できず、どちらか一方が必須です。
  • options JSON Object Optional プッシュオプション
    request_id String Optional 顧客がリクエストを識別するためのカスタムオプションフィールドで、レスポンス時に返されます。
    custom_args JSON Object Optional 顧客がカスタマイズしたオプションフィールドで、コールバック時に顧客に返されます。

    from

    現在の業務の送信元です。値はString型で、オプションです。

    Sample Requests

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

    to

    プッシュ対象のデバイスオブジェクトで、プッシュを送信できるデバイスのリストを示します。MTPushは、Registration IDとブロードキャストの2つの方法を提供しています。

    Push target

    Keyword Type Meaning Description Note
    all String ブロードキャスト すべてのデバイスにプッシュ 過去30日間にアクティブだった対象デバイスにプッシュされます。
    registration_id JSON Array 登録ID 配列。複数の登録ID間の関係はOR(和集合)です。 デバイスID。一度に最大1,000件のメッセージをプッシュできます。
    tag JSON Array タグ 配列。複数のタグ間の関係はOR(和集合)です。 タグを使用して大規模なデバイス属性、ユーザー属性のサブグループにプッシュできます。
  • 一度に最大20個までプッシュ可能。
  • 有効なタグの構成:文字(大文字小文字区別)、数字、アンダースコア、漢字。
  • 制限:各タグの長さは40バイトに制限されています(長さの判定にはUTF-8エンコーディングが必要です)。
  • tag_and JSON Array タグAND 配列。複数のタグ間の関係はAND(積集合)です。 tagとの区別に注意してください。一度に最大20個までです。
    tag_not JSON Array タグNOT 配列。複数のラベル間では、まず複数のラベルの結合集合を取り、その結果に対して補集合を取ります。 一度に最大20個までプッシュ可能です。
    alias JSON Array エイリアス 配列。複数のエイリアス間の関係はOR(和集合)です。 エイリアスでユーザーを識別できます。
  • 1つのデバイスは1つのエイリアスにのみバインドできますが、複数のデバイスが同じエイリアスにバインドできます。
  • 一度に最大1000個までプッシュ可能です。
  • 有効なエイリアスの構成:文字(大文字小文字区別)、数字、アンダースコア、漢字。
  • 制限:各エイリアスの長さは40バイトに制限されています(長さの判定にはUTF-8エンコーディングが必要です)。

  • 配列内の複数の値間の暗黙的な関係はOR(和集合)です。ただし、tag_andは異なり、配列内の複数の値間の関係はAND(積集合)です。

    tag_notが単独で使用される場合、ブロードキャストユーザー間でtag_not処理を行います。

    これらの型は共存できます。共存時の複数の項目間の暗黙的な関係はAND(積集合)です。例:

    "to" : {"tag" : [ "tag1", "tag2"], "tag_and" : ["tag3", "tag4"], "tag_not" : ["tag5", "tag6"] }

    まず"tag"フィールドの結果を計算***tag1 or tag2 = A***;

    次に"tag_and"フィールドの結果を計算***tag3 and tag4 = B***;

    次に"tag_not"フィールドの結果を計算*** not (tag5 or tag6) = C***;

    "to"の最終結果は***A and B and C*** です。


    Sample Requests

    • 全員にプッシュ(ブロードキャスト):
    { "to": "all", }
                  
                  {
      "to": "all",
    }
    
                
    このコードブロックはフローティングウィンドウ内に表示されます
    • 複数の登録IDにプッシュ:
    { "to": { "registration_id": [ "4312kjklfds2", "8914afd2", "45fdsa31" ] } }
                  
                  {
      "to": {
        "registration_id": [
          "4312kjklfds2",
          "8914afd2",
          "45fdsa31"
        ]
      }
    }
    
                
    このコードブロックはフローティングウィンドウ内に表示されます

    body

    リクエストの本体です。サポートされているフィールドは以下のとおりです:

    Keyword Type Option Description
    platform String または JSON Array Required プッシュプラットフォーム
    notification JSON Object Optional
  • クライアントにプッシュされる通知内容。
  • messageとは同時に存在できず、どちらか一方が必須です。
  • message JSON Object Optional
  • クライアントにプッシュされるメッセージ内容。
  • notificationとは同時に存在できず、どちらか一方が必須です。
  • options JSON Object Optional プッシュオプション

    platform

    MTPushは現在、Webプラットフォームのプッシュのみをサポートしているため、platformで指定するキーワードは"web"です。

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

    notification

    notificationオブジェクトは、プッシュされるエンティティコンテンツオブジェクトの1つ(もう1つはmessage)で、通知としてwebにプッシュされます。

    Keyword Type Option Meaning Description
    web JSON Object Required プラットフォームプロパティ プラットフォームのプッシュパラメータ。webを参照してください。

    web

    Webプラットフォームの通知です。

    Keyword Type Option Meaning Description
    alert String または JSON Object Required 内容 メッセージ内容自体で、ここで指定すると、上位で指定されたalert情報を上書きします。
    url String Required webプッシュURL 通知クリック時のジャンプ先アドレス
    title String Optional タイトル メッセージのタイトル
    Extras JSON Object Optional 拡張フィールド ここでは、業務用途のためにJSON形式のKey/Value情報をカスタマイズできます。
    icon String optional 通知アイコン 推奨サイズ192*192px(必須の制限なし)。サイズ上限1M、形式はJPG、PNG、GIFに限定。Chrome、Firefoxをサポート(SafariとEdgeシステムはデフォルトでカスタマイズ不可)。
    image String Optional 通知の大きな画像 推奨サイズ360*180px(必須の制限なし)。サイズ上限1M、形式はJPG、PNG、GIFに限定。Chrome、Edgeをサポート(FirefoxとSafariはサポートしない)。
    { "notification": { "web": { "alert": "hello, Push!", "title": "Push Test", "url":"http://www.google.com", "icon":"", "image":"", "extras": { "news_id": 134, "my_key": "a value" } } } }
                  
                  {
        "notification": {
            "web": {
                "alert": "hello, Push!",
                "title": "Push Test",
                "url":"http://www.google.com",
                "icon":"",
                "image":"",
                "extras": {
                    "news_id": 134,
                    "my_key": "a value"
                }
            }
        }
    }
    
                
    このコードブロックはフローティングウィンドウ内に表示されます

    message

    インアプリメッセージまたはカスタムメッセージです。この部分の内容はブラウザに表示されません。SDKがメッセージを受信后、Webに伝送し、Web側で業務ロジックを処理します。

    メッセージには以下のフィールドが含まれます:

    Keyword Type Option Description
    msg_content String または JSON Object Required メッセージ内容
    title String Optional メッセージのタイトル
    content_type String Optional メッセージのコンテンツタイプ
    Extras JSON Object Optional JSON形式のオプションパラメータ

    例:

    { "message": { "msg_content": "Hi,Push", "content_type": "text", "title": "msg", "extras": { "key": "value" } } }
                  
                  {
      "message": {
        "msg_content": "Hi,Push",
        "content_type": "text",
        "title": "msg",
        "extras": {
          "key": "value"
        }
      }
    }
    
                
    このコードブロックはフローティングウィンドウ内に表示されます

    options

    プッシュオプションです。以下のオプションが利用可能です:

    キーワード タイプ オプション 意味 説明
    time_to_live Int または String 任意 オフラインメッセージの保持期間(秒)
  • プッシュ中にユーザーがオフラインの場合、指定された期間オフラインメッセージを保持し、ユーザーがオンラインになった際に再度プッシュされます。
  • デフォルトは86400(1日)、最大は15日です。システムブラウザがサポートする最大値が有効値より小さい場合、システムの最大値が適用されます。
  • 0に設定するとオフラインメッセージは保持されず、現在オンラインのユーザーのみがプッシュを受け取ります。
  • override_msg_id Long 任意 上書きするメッセージID 現在のプッシュが以前のプッシュを上書きする場合、ここに以前のプッシュのmsg_idを入力して上書き効果を実現します。つまり:
  • このmsg_idに対応するオフラインメッセージは上書きされた内容になります。たとえユーザーがウェブ上でmsg_idを既に受け取っていても、通知バーがクリアされていない場合、新しいメッセージ内容が以前の通知を上書きします。
  • 上書き機能は1日の時間制限内で有効です。指定されたmsg_idが上書き時間制限内に存在しない場合、エラー1003が返され、無効なメッセージ上書き操作であることを示し、現在のメッセージはプッシュされません。
  • big_push_duration Int 任意 スロープッシュの期間(分)
  • スロープッシュとも呼ばれ、元の可能な限り速いプッシュ速度を減少させ、指定されたn分間にわたってターゲットユーザーに均等にプッシュを分配します。最大値は1440です。
  • 同時に存在できるスロープッシュは最大20件です。
  • 設定されていない場合、スロープッシュではありません。
  • web_buttons JSON オブジェクト 任意 通知メッセージにボタンを追加
  • 最大2つのボタンを追加できます。
  • ボタン名とリダイレクトリンクを設定できます。詳細はweb_buttonsを参照してください。
  • multi_language JSON オブジェクト 任意 多言語プッシュ設定 プッシュ内容の多言語適応設定。詳細はmulti_languageの説明を参照してください。
    third_party_channel JSON オブジェクト 任意 Webシステムチャネル構成情報 システムチャネルが構成されているユーザーにのみ有効なパラメータです。詳細はthird_party_channelの説明を参照してください。
    plan_id String 任意 プッシュ計画識別子 まず計画識別子の値を作成する必要があります。これはコンソールまたはAPIを介して作成できます。
    cid String 任意 重複プッシュを防ぐためのプッシュリクエスト識別子 英字、数字、アンダースコア、ハイフンのみ許可され、最大長は64文字です。このフィールドは同じAppKeyの下で一意である必要があります。

    multi_language

    このフィールドはEngageLabプッシュサービスの多言語プッシュ機能です。異なる言語のユーザーにカスタマイズされた通知コンテンツをプッシュできます。プッシュリクエストで複数の言語とそれに対応するメッセージ内容、タイトルを指定することで、ユーザーの言語設定に応じて適切なプッシュ通知を送信できます。

    Request Parameters
    Keyword Type Option Meaning Description
    en string Optional 多言語キー ユーザーの言語に対応します。キーコードは付録を参照してください。
    content string Optional メッセージ内容 ユーザーの言語に基づいて、notification.web.alert、message.msg_contentのデータを置き換えます。
    title string Optional メッセージタイトル ユーザーの言語に基づいて、notification.web.title、message.titleのデータを置き換えます。
    Request Example
    HTTP request method: Post Request URL: /v4/push POST data format: json POST data example: { "options": { "multi_language": { "en": { "content": "", "title": "", } } } }
                  
                     HTTP request method: Post
       Request URL: /v4/push
       POST data format: json
       POST data example:
       {
        "options": {
          "multi_language": {
            "en": {
              "content": "",
              "title": "",
            }
          }
        }
       }
    
                
    このコードブロックはフローティングウィンドウ内に表示されます
    Response Example
    成功時: { } 失敗時: { "code":400, "data":"", "message":"エラー情報" }
                  
                  成功時:
    {
       
    }
    
    失敗時:
    {   
        "code":400,  
        "data":"",
      "message":"エラー情報"
    }   
    
                
    このコードブロックはフローティングウィンドウ内に表示されます

    web_buttons

    web_buttons パラメータを使用して、ボタンの id、テキスト、アイコン、および URL を記述します。パラメータの説明は以下の通りです:

    キーワード タイプ オプション 意味 説明
    id 必須 String ボタンの id chrom48+ バージョンからサポート
    text 必須 String ボタンの内容 chrom48+ バージョンからサポート
    icon 任意 String ボタンのアイコン chrom50+ バージョンからサポート
    url 必須 String ボタンのリダイレクトリンク chrom48+ バージョンからサポート。web_buttons が使用される場合、web パラメータ内の url フィールドは無効になります

    呼び出し例は以下の通りです:

    [ { "id": "like-button", "text": "いいね", "icon": "http://i.imgur.com/N8SN8ZS.png", "url": "https://yoursite.com" }, { "id": "read-more-button", "text": "続きを読む", "icon": "http://i.imgur.com/MIxJp1L.png", "url": "https://yoursite.com" } ] #### third_party_channel このフィールドはWebシステムチャネルの個別情報を入力するためのものです。キー名はw3pushで、値はJsonオブジェクトです。このオブジェクトには、String型のdistributionフィールド(オプション)のみが含まれます。 | **Keyword** | **Type** | **Option** | **Meaning** | **Description** | | --- | --- | --- | --- | --- | | distribution | Required | String | Engagelabとシステムチャネルが共存する場合の配信優先度設定。 | 値は空文字列にできません。<li>first_ospush: システムチャネルを優先してプッシュし、Engagelabチャネルを使用しません。<li>mtpush: Engagelabチャネルを強制的に使用してプッシュします。<li>secondary_push: Engagelabを優先し、Engagelabがオンラインでない場合はシステムチャネルを使用します。システムチャネルは補助的な方法として使用されます(この方法を推奨)。<li>ospush:システムチャネルのみを使用してプッシュを強制的に配信します。| Example: ```json { "third_party_channel":{ "w3push":{ "distribution":"mtpush" } } }
                  
                  [
      {
        "id": "like-button",
        "text": "いいね",
        "icon": "http://i.imgur.com/N8SN8ZS.png",
        "url": "https://yoursite.com"
      },
      {
        "id": "read-more-button",
        "text": "続きを読む",
        "icon": "http://i.imgur.com/MIxJp1L.png",
        "url": "https://yoursite.com"
      }
    ]
    
    
    #### third_party_channel
    
    このフィールドはWebシステムチャネルの個別情報を入力するためのものです。キー名はw3pushで、値はJsonオブジェクトです。このオブジェクトには、String型のdistributionフィールド(オプション)のみが含まれます。
    
    | **Keyword** | **Type** | **Option** | **Meaning** | **Description** |
    | --- | --- | --- | --- | --- |
    | distribution | Required | String | Engagelabとシステムチャネルが共存する場合の配信優先度設定。 | 値は空文字列にできません。<li>first_ospush: システムチャネルを優先してプッシュし、Engagelabチャネルを使用しません。<li>mtpush: Engagelabチャネルを強制的に使用してプッシュします。<li>secondary_push: Engagelabを優先し、Engagelabがオンラインでない場合はシステムチャネルを使用します。システムチャネルは補助的な方法として使用されます(この方法を推奨)。<li>ospush:システムチャネルのみを使用してプッシュを強制的に配信します。| 
    
    Example:
    ```json
    {
      "third_party_channel":{
        "w3push":{
          "distribution":"mtpush"
        }
      }
    }
    
                
    このコードブロックはフローティングウィンドウ内に表示されます

    request_id

    リクエストのIDです。顧客がリクエストを識別し、レスポンスを返します。

    Sample Requests

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

    custom_args

    ユーザー定義のオプションフィールドです。レスポンス時には返されませんが、コールバック時に返されます。

    { "custom_args":"business info" }
                  
                  {
      "custom_args":"business info"
    }
    
                
    このコードブロックはフローティングウィンドウ内に表示されます

    Response parameters

    Success Response

    field type option description
    request_id String Optional リクエスト時に送信されたカスタムIDで、レスポンス時にそのまま返されます。
    message_id String Required メッセージを一意に識別するメッセージID。
    < HTTP/1.1 200 OK < Content-Type: application/json {"request_id": "18", "msg_id": "1828256757"}
                  
                  < HTTP/1.1 200 OK
    < Content-Type: application/json
    {"request_id": "18", "msg_id": "1828256757"}
    
                
    このコードブロックはフローティングウィンドウ内に表示されます

    Failure response

    HTTPステータスコードは4xxまたは5xxで、レスポンスボディには以下のフィールドが含まれます。

    Field Type Option Description
    code int required エラーコード。詳細はreturn-code の説明を参照してください。
    message String required エラー詳細
    { "code": 3002, "message": "Push.template field must be set correctly when type is template" }
                  
                  {
        "code": 3002,
        "message": "Push.template field must be set correctly when type is template"
    }
    
                
    このコードブロックはフローティングウィンドウ内に表示されます

    Response

    HTTP status code

    参照:HTTP-Status-Code

    Return code

    Code Description Detailed explanation HTTP status code
    20101 プッシュパラメータが無効です。 registration_idが無効であるか、現在のappkeyに属していません。 400
    21001 HTTP Postメソッドのみをサポートしています。 Getメソッドはサポートしていません。 405
    21002 必須パラメータが不足しています。 修正が必要です。 400
    21003 パラメータ値が無効です。 修正が必要です。 400
    21004 認証に失敗しました。 修正が必要です。詳細は呼び出し認証を参照してください。 401
    21005 メッセージ本体が大きすぎます。 修正が必要です。Notificationの長さは2048バイトに制限されています。 400
    21008 app_keyパラメータが無効です。 修正が必要です。渡したappkeyがアプリケーション情報のものと一致するか、余分なスペースがないかを慎重に確認してください。 400
    21009 内部システムエラー 修正が必要です。 400
    21011 条件に一致するプッシュ対象がありません。 確認してください。 400
    21015 リクエストパラメータの検証に失敗しました。 予期しないパラメータが存在します。 400
    21016 リクエストパラメータの検証に失敗しました。 パラメータの型が正しくないか、パラメータの長さが制限を超えています。 400
    21030 内部サービスタイムアウト 後で再試行してください。 503
    23006 パラメータエラー big_push_durationの最大値は1440です。 400
    23008 インターフェース速度制限 単一アプリケーションのプッシュインターフェースのQPSが上限(500 QPS)に達しています。 400
    27000 システムメモリエラー 再試行してください。 500
    27001 パラメータエラー 認証情報が空です。 401
    27008 パラメータエラー third_party_channelのdistributionが空ではないのに、notificationのalert内容が空です。 401
    27009 パラメータエラー third_party_channelのdistributionの形式が無効または空です。 401

    Push Restrictions

    Channel Subject length Content length Other instructions
    Engagelab 制限なし(メッセージ本体の総サイズに制限あり) 制限なし(メッセージ本体の総サイズに制限あり) Notification MTPushの長さは4000バイトに制限されています。
    システムチャネル <20文字(英字40文字)
  • 通知センターとロック画面状態では最大110文字、漢字55文字を表示できます。
  • トップポップアップでは最大62文字、漢字31文字を表示でき、超過分は省略記号で表示されます。
  • なし

    Multi-language code

    言語 コード
    英語 en
    アラビア語 ar
    中国語(簡体) zh-Hans
    中国語(繁体) zh-Hant
    チェコ語 cs
    デンマーク語 da
    オランダ語 nl
    フランス語 fr
    ドイツ語 de
    ヒンディー語 hi
    イタリア語 it
    日本語 ja
    韓国語 ko
    マレー語 ms
    ロシア語 ru
    スペイン語 es
    タイ語 th
    ベトナム語 vi
    インドネシア語 id
    ノルウェー語 no
    スウェーデン語 sv
    ポーランド語 pl
    トルコ語 tr
    ヘブライ語 he
    ポルトガル語 pt
    ルーマニア語 ro
    ハンガリー語 hu
    フィンランド語 fi
    ギリシャ語 el
    ウクライナ語 uk
    ラオス語 lo
    ポルトガル語(ポルトガル) pt_PT
    ポルトガル語(ブラジル) pt_BR
    スペイン語(アルゼンチン) es_AR
    スペイン語(スペイン) es_ES
    スペイン語(ラテンアメリカ) es_419
    icon
    お問い合わせ