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は単独で使用できません。他の5種類のうち少なくとも1つが必要です。値の配列の長さが0の場合、その型は存在しません。

これらの型は共存できます。共存時の複数の項目間の暗黙的な関係は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

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

Keyword	Type	Option	Meaning	Description
time_to_live	Int または String	Optional	オフラインメッセージ保持期間（秒）	プッシュ時にユーザーがオンラインでない場合、指定した期間のオフラインメッセージを保持し、ユーザーがオンラインになったときに再プッシュできます。デフォルト値は86400（1日）、最大値は15日です。システムブラウザがサポートする最大値が渡された有効値より小さい場合は、システムの最大値を基準とします。このパラメータを0に設定すると、オフラインメッセージは保持されません。プッシュ時にオンラインのユーザーのみがメッセージを受信できます。
override_msg_id	Long	Optional	上書きするメッセージのID	現在のプッシュが以前のプッシュを上書きする場合、以前のプッシュのmsg_idにより上書き効果が発生します。すなわち： msg_idのオフラインで受信したメッセージが上書きされます。msg_idのWebユーザーが既にメッセージを受信していても、通知バーがクリアされていない場合は、新しいメッセージ内容が以前の通知を上書きします。上書き機能の有効期限は1日です。指定した期限内にmsg_idが存在しない場合は、1003エラーが返され、有効な上書き操作ではないことを示し、現在のメッセージはプッシュされません。
big_push_duration	Int	Optional	定速プッシュ期間（分）	スロープッシュとも呼ばれ、元のプッシュ速度をできるだけ低下させ、指定したn分間内に対象ユーザーに均等にプッシュします。最大値は1440です。同時に存在できる定速プッシュは最大20件です。このパラメータを設定しない場合は、定速プッシュではありません。
multi_language	json object	Optional	多言語プッシュ設定	プッシュコンテンツの多言語対応設定。詳細はmulti_languageを参照してください。
third_party_channel	JSON Object	Optional	Webシステムチャネルの設定情報	システムチャネルを設定したユーザーのみ有効なパラメータ。third_party_channelを参照してください。
plan_id	String	Optional	プッシュ計画識別子	事前に計画識別値を作成する必要があります。コンソールまたはAPIで作成できます。
cid	String	Optional	プッシュリクエスト識別子（重複プッシュ防止用）	文字、数字、アンダースコア、マイナス記号のみを許可し、長さは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":"エラー情報"
}

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

third_party_channel

このフィールドはWebシステムチャネルの個別情報を入力するためのものです。キー名はw3pushで、値はJsonオブジェクトです。このオブジェクトには、String型のdistributionフィールド（オプション）のみが含まれます。

Keyword	Type	Option	Meaning	Description
distribution	Required	String	Engagelabとシステムチャネルが共存する場合の配信優先度設定。	値は空文字列にできません。 first_ospush: システムチャネルを優先してプッシュし、Engagelabチャネルを使用しません。 mtpush: Engagelabチャネルを強制的に使用してプッシュします。 secondary_push: Engagelabを優先し、Engagelabがオンラインでない場合はシステムチャネルを使用します。システムチャネルは補助的な方法として使用されます（この方法を推奨）。 ospush：システムチャネルのみを使用してプッシュを強制的に配信します。

Example：

{ "third_party_channel":{ "w3push":{ "distribution":"mtpush" } } }

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

Language	Language Code
English	en
Arabic	ar
Chinese (Simplified)	zh-Hans
Chinese (Traditional)	zh-Hant
Czech	cs
Danish	da
Dutch	nl
French	fr
German	de
Hindi	hi
Italian	it
Japanese	ja
Korean	ko
Malay	ms
Russian	ru
Spanish	es
Thai	th
Vietnamese	vi
Indonesian	id
Norwegian	no
Swedish	sv
Polish	pl
Turkish	tr
Hebrew	he
Portuguese	pt
Romanian	ro
Hungarian	hu
Finnish	fi
Greek	el