Web SDK API
SDK は AppKey に対応するデータセンターの接続先と統計送信先を自動取得します。フランクフルトとバージニアも対象です。baseUrl、report_url、webSocketUrl を手動で指定する必要はありません。
認証
開発者が初期化を実行する場合、必要な情報を渡す必要があります。このデータ構造は開発者サーバーによって生成され、ブラウザに返送され、開発者がブラウザに実行を許可するMTpush初期化に使用されます。開発者は、このデータを取得するために呼び出すことができるすべてのユーザーが正当なユーザーであることを保証する必要があります。
データ構造の初期化
interface MTInitInfo {
website_push_id: string;
code: number;
master_secret: string;
passwd: string;
pull: number;
regid: string;
sess: string;
tagalias: number;
uid: number;
vapid_pubkey: string;
}
type dataType = {
code: number,
content?: string | { code: number; [key: string]: unknown },
message: string,
};
interface InitType {
report_url?: string; // Report URL, used for private cloud or custom deployments
baseUrl?: string; // Server domain; when used together with report_url, the private cloud or custom deployment logic is used
userLang?: string; // Defaults to navigator.language and must be a language value supported by the browser
safari_url?: string; // Safari push test field
appkey: string; // AppKey of the application registered on the EngageLab platform, required
user_str: string; // Unique user identifier, required
swUrl?: string; // Default: "/sw" + sdkEnv.prefix
is_temporary?: "n" | "t"; // Default: "n"
debugMode?: boolean; // Default: false
webSocketUrl?: string; // If not provided, baseUrl will be used
fail?: (data: dataType | undefined) => void; // Initialization failure callback
success?: (data: dataType | undefined) => void; // Initialization success callback
webPushcallback?: def;
canGetInfo?: (d: MTInitInfo) => void;
custom?: (Callback: () => void) => void; // Callback for custom prompts; call Callback to request notification permission
maOpen?: boolean; // Whether to enable the ma-sdk module
maChannel?: string; // Channel name used by ma-sdk; default: default-channel
appName?: string; // Website name used by ma-sdk for reporting
userIdentity?: { userId?: string; anonymousId?: string }; // User identity used by ma-sdk
maCompletion?: (code: number, msg: string) => void; // ma-sdk initialization completion callback
openUrl?: string; // Redirect link when clicking a notification
encodeSwUrl?: boolean; // Whether to encode swUrl
regidSearchPath?: string; // Page path for querying Registration ID
}
- パラメータ説明:
- openUrl:通知クリック時に開くURL
- 通知送信時にURLが指定されていない場合、この値をリダイレクトリンクとして使用;
- 未設定の場合は統合ドメインへリダイレクト;
- マルチドメイン統合では、このパラメータで対応するURLへリダイレクト可能;
- encodeSwUrl:swUrlをエンコードするか
- swUrlに@などの特殊文字が含まれ、サーバーがそのURLへのアクセスを制限している場合にService Worker登録が失敗することがある;再登録の仕組みを追加し、リトライ時にswUrlをエンコードすること。
- regidSearchPath:Registration ID を検索するページのパス。デフォルトは /engagelab/regid。Registration ID 検索機能ガイド を参照。
- openUrl:通知クリック時に開くURL
同じスコープ内では1つのサービスワーカーのみ登録できます。初期化成功時に「'subscribe' on 'PushManager' の実行に失敗しました: サブスクリプションに失敗しました - アクティブなService Workerがありません」のようなエラーが報告された場合は、他のサービスワーカーとの競合を確認してください。サービスワーカーを統合するか、サービスワーカーのスコープを解決する必要がある場合があります。
SDK初期化
インターフェース説明
インターフェースを初期化します。
window.MTpushInterface.init(Object:InitType)
パラメータ説明
- 詳細については、[InitTypeの説明](/ja_JP/docs/web-push/sdk/web-sdk-api#Initialize data structure)を参照してください。
- コールバックオブジェクトデータの説明:
| パラメータ名 | パラメータ型 | パラメータの説明 |
|---|---|---|
| code | number | 戻りコード、0は成功を意味し、その他は失敗を意味します。エラーコードを参照してください |
| message | string | 結果の説明 |
| content | string | Object | 失敗の詳細。初期化失敗(1003)の場合、サーバーのエラーコード code を含むオブジェクトが返ることがあります。サーバー初期化エラーコードを参照してください。 |
呼び出し例
const appkey = "your_appkey";
const userStr = "adminDemo";
MTpushInterface.init({
appkey: appkey,
user_str: userStr,
fail(data) {
console.log("Online push setup failed", data);
},
success(data) {
console.log("Online push setup successful", data);
},
webPushcallback(code, tip) {
console.log("Status code and message", code, tip);
},
canGetInfo(data) {
// RegId is available here, and initialization config data can also be read from data.
console.log("Obtained RegId", MTpushInterface.getRegistrationID(), data);
// MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "swefgwwefwfwfwf" });
},
custom: (requestPermission) => {
// For custom prompt settings, call requestPermission during an appropriate user action to request notification permission.
document.getElementById("subscribe")?.addEventListener("click", () => {
if (Notification.permission === "default") {
requestPermission();
} else if (Notification.permission === "denied") {
console.log("Notification permission is denied and cannot be requested");
} else {
console.log("Notification permission has already been granted");
}
});
},
});
RegistrationIDの取得
インターフェース説明
このAPIを呼び出して、現在のアカウントに対応するRegistrationIDを取得します。初期化署名が成功した後にのみ対応する値が返され、それ以外の場合は空の文字列が返されます。このメソッドはcanGetInfoコールバックがトリガーされた後に呼び出す必要があります。
window.MTpushInterface.getRegistrationID()
呼び出し例
var rid = window.MTpushInterface.getRegistrationID();
プッシュの停止
このAPIを呼び出して、バックグラウンドと確立されたプッシュ永続接続を切断し、プッシュメッセージの受信を停止します。
window.MTpushInterface.mtPush.stopPush()
プッシュメッセージの監視
インターフェース説明
初期化の前にメッセージリスナーを呼び出すことを推奨します。
window.MTpushInterface.onMsgReceive(fn)
パラメータ説明
| パラメータ名 | パラメータ型 | パラメータの説明 |
|---|---|---|
| fn | function | メッセージ受信と処理関数 |
呼び出し例
window.MTpushInterface.onMsgReceive(function (res) {
if(res.type===0){
// res.data.messages[]
// res.data.messages[].msg_id
// res.data.messages[].title
// res.data.messages[].content
// res.data.messages[].extras
}else{
// res.data.title
}
});
戻りデータ
| パラメータ名 | パラメータ型 | パラメータの説明 |
|---|---|---|
| type | number | |
| data | Object | メッセージコンテンツ |
Engagelabチャネルメッセージ配列(messages)
| パラメータ名 | パラメータ型 | パラメータの説明 |
|---|---|---|
| msg_id | string | メッセージID |
| title | string | メッセージタイトル |
| content | string | メッセージコンテンツ |
| extras | Object | メッセージ追加フィールド |
システムチャネルメッセージデータ
w3cインターフェースNotificationOptionsをサポートしています。詳細についてはmdn web docsを参照してください。
プッシュサービス状態の確認
window.MTpushInterface.getPushAuthority()
戻されるデータ構造は次のとおりです:
{
mtPush: {
code:1, //1は成功、-1は初期化中、0は失敗
msg:'success'
},
webPush: {
code:1, // 0 webpushは使用不可(ブラウザがサポートしていません)1は使用可 2権限が無効 3権限が確認されていません
msg:'success'
}
}
- WebPushオブジェクトのエラーコード:
以下のステータスコードは getPushAuthority().webPush.code と webPushcallback(code, tip) に適用されます。初期化の fail コールバックのコードとは別です。
| コード | メッセージ | 備考 |
|---|---|---|
| 0 | ブラウザが通知APIをサポートしていません | ブラウザが通知APIをサポートしていません |
| 1 | 通知の権限が利用可能で、メッセージの購読に成功しました。 | 通知の権限が利用可能で、メッセージの購読に成功しました。 |
| 2 | 通知の権限が無効化されており、メッセージの購読に失敗しました。 | 通知の権限が無効化されており、メッセージの購読に失敗しました。 |
| 3 | 通知の権限が確認されておらず、メッセージの購読が実行されていません。 | 通知の権限が確認されておらず、メッセージの購読が実行されていません。 |
| -1 | ブラウザがService Workerをサポートしていません。 | ブラウザがService Workerをサポートしていません。 |
| -2 | Service WorkerがHTTPをサポートしていません。 | Service WorkerがHTTPプロトコルをサポートしていません。 |
| -3 | Service Workerの登録に失敗しました。 | Service Workerの登録に失敗しました。 |
| -4 | 通知の権限は利用可能ですが、メッセージの購読に失敗しました。 | 通知の権限は利用可能ですが、メッセージの購読に失敗しました。 |
| -5 | 購読がキャンセルされました。 | 購読がキャンセルされました。 |
ブラウザ通知権限の取得
window.MTpushInterface.getWebPermission()
戻りパラメータの説明
- granted : 使用可
- denied : 無効
- default: 権限が確認されていません
カスタムメッセージレポート
カスタムメッセージのデータ統計を行う必要がある場合は、カスタムレポートAPIを使用してください。
表示レポート:
window.MTpushInterface.customDisplayReport('msg_id');//msg_idはカスタムメッセージのmsg_idです
クリックレポート:
window.MTpushInterface.customClickReport('msg_id');//msg_idはカスタムメッセージのmsg_idです
切断監視
インターフェース説明
初期化が成功した後に切断が発生した場合、SDKは自動的に再接続と署名を試みます。 初期化の前にこのイベントリスナーを呼び出すことを推奨し、このイベントを受信した後に再度初期化を呼び出してください。
window.MTpushInterface.mtPush.onDisconnect(fn)
呼び出し例
window.MTpushInterface.mtPush.onDisconnect(function () {
});
ブラウザサブスクリプションのキャンセル
通知のサブスクリプションを解除します。一部のアカウントのプライバシーレベルが高い場合、アカウントをログアウトするときに通知を受信する必要がない場合にこのメソッドを使用できます。
MTpushInterface. unSubscribe();
TagsAliasの設定
window.MTpushInterface.setTagsAlias({})
MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });
パラメータ説明
| パラメータ名 | パラメータ型 | パラメータの説明 |
|---|---|---|
| tags | string[] | 必須、配列の最大長は1000、各要素の最大長は40文字 |
| alias | string | 必須、最大40文字 |
インターフェース説明
開発者はこのインターフェースを通じて tag と alias を設定できます。このインターフェースは上書きロジックであることにご注意ください。空文字列を設定すると、既存の tag と alias が削除されます。
通知言語の設定
MTpushInterface.setLan(lan)
MTpushInterface.setLan(lan, (err) => {
alert(err ? "通知言語の設定に失敗しました:" + err : "通知言語の設定に成功しました");
});
パラメータ説明
| パラメータ名 | パラメータ型 | パラメータ説明 |
|---|---|---|
| パラメータ1 | string | 必須。ISO 639-1 言語コード形式の言語パラメータ。例:中国語は "cn"、英語は "en"、日本語は "ja" |
| パラメータ2 | Function | 任意のコールバック関数。設定完了後に呼び出されます。err パラメータがある場合はエラー情報を示し、ない場合は成功を示します |
インターフェース説明
開発者はこのAPIを使用して通知言語を手動で設定できます。設定に成功すると、SDK はその言語を保存します。次回初期化時に userLang が渡されない場合、ローカルに保存された言語が優先して使用されます。
カテゴリプロンプトの複数表示
window.MTpushInterface.promptPushCategories();
インターフェース説明
ユーザーがプッシュ通知をサブスクライブした後、開発者は必要に応じてカテゴリプロンプトを複数回表示できます。これはSDKの初期化後に呼び出す必要があります。
Safariコールバックの互換性
SDK v3.3.8以降では、Safariの現在の購読方式に応じてプッシュチャネルが選択されます。コールバックを利用できるかどうかは、購読方式、イベント発生時のページ状態、およびリスナーの登録タイミングによって異なります。
| 購読方式またはページ状態 | 表示コールバック | クリックコールバック |
|---|---|---|
Legacy Safari Website Push購読(従来のdeviceTokenを保持) |
ページ側の表示コールバックを確実に受信できません | ページ側のクリックコールバックを確実に受信できません |
| W3C Push購読で、イベント発生時にService Workerの制御下にあるページが開いている | メッセージ受信時に実行できます | ユーザーが通知をクリックしたときに実行できます |
| W3C Push購読で、イベント発生時にメッセージを受信できるページがない | 実行されず、後からページを開いても再送されません | 実行されません。通知から対象ページを開くことはできますが、新しいページにコールバックは再送されません |
| イベント発生後にリスナーを登録 | 再送されません | 再送されません |
ページ側コールバック、システム通知の表示、サーバー側の統計はそれぞれ独立した仕組みです。ページ側コールバックを受信できなくても、通知が表示されなかったことや、配信・表示・クリックデータがサーバーに記録されなかったことを意味しません。
プッシュメッセージ表示コールバック
インターフェース説明
初期化の前にメッセージリスナーを呼び出すことを推奨します。
呼び出し例
window.MTpushInterface.onMsgDisplay((msgData) => {});
パラメータ説明
通知メッセージコールバックパラメータmsgDataの説明:
{
engagelab_ntf_or_msg: number;
engagelab_appkey: string;
engagelab_passwd: string;
engagelab_uid: number;
engagelab_m_str: string;
engagelab_a_str: string;
type: number;
title: string;
content: string;
msg_id: string;
}
アプリ内メッセージコールバックパラメータmsgDataの説明:
{
title: string;
content: string;
msg_id: string;
ntf_or_msg: number;
type: number;
}
この型はコンソールの標準アプリ内テンプレートに対応し、type は数値 0 です。カスタム HTML のコールバックデータはテンプレートの実装によって決まります。
注:
アプリ内メッセージのHTML編集モードでは、コールバックパラメータ
titleとcontentは空の文字列です。Safariのコールバックには、上記の互換性条件が適用されます。SDKの初期化前にリスナーを登録し、イベント発生時にService Workerの制御下にあるページが存在することを確認してください。
プッシュメッセージクリックコールバック
インターフェース説明
初期化の前にメッセージリスナーを呼び出すことを推奨します。
呼び出し例
window.MTpushInterface.onMsgClick((msgData) => {});
パラメータ説明
通知メッセージコールバックパラメータmsgDataの説明:
{
engagelab_ntf_or_msg: number;
engagelab_appkey: string;
engagelab_passwd: string;
engagelab_uid: number;
engagelab_m_str: string;
engagelab_a_str: string;
type: number;
title: string;
content: string;
msg_id: string;
target_event: string | null;
position: string; // クリック位置、'msgBody' | ボタンID
}
アプリ内メッセージコールバックパラメータmsgDataの説明:
{
position: 'msgBody' | 'mainBtn' | 'subBtn' | 'closeBtn';
msg_id: number;
title: string;
content: string;
extras: object | null;
ntf_or_msg: number;
strategy: object | null;
target_event: unknown[];
type: number;
icon: string;
}
注:
- アプリ内メッセージのHTML編集モードでは、
positionの値は開発者によって決定され、コールバックパラメータtitleとcontentは空の文字列です。- Safariのコールバックには、上記の互換性条件が適用されます。通知のクリック時にメッセージを受信できるページがない場合、対象ページを開いてもクリックコールバックは再送されません。
エラーコード
以下は初期化コールバックの外側の data.code です。サーバー側の具体的な失敗原因は data.content.code に含まれます。同じ数値でも、この2つのフィールドでは意味が異なる場合があります。
| code | message | 意味 |
|---|---|---|
| 0 | success | 呼び出し成功 |
| 1000 | unknown error | 不明なエラー。content が do not support websocket の場合、ブラウザーが WebSocket をサポートしていません。 |
| 1001 | initing , please try again later | 初期化中、後で再試行してください |
| 1002 | invalid config | 初期設定エラー |
| 1003 | init failed | 初期化に失敗しました。コールバックの content とコンソール出力を確認してください。content.code の意味はサーバー初期化エラーコードを参照してください。 |
| 1004 | init timeout | 初期化タイムアウト |
| 1005 | network error | ネットワークエラー、ネットワークがないかwebsocketに接続できません |
| 1006 | failed to get baseUrl and reportUrl | get-webaddr API リクエストが失敗しました。詳細については、コールバック内の content フィールドを参照してください |
| 1007 | authentication failed | 認証に失敗しました。content には認証 API のエラー説明またはネットワークエラー情報が入ります。認証失敗の詳細を参照してください。 |
| 1008 | region restricted | 地域制限。SDK は認証 API のコード 7017 をこのコードに変換し、content は REGION_RESTRICTED になります。 |
サーバー初期化エラーコード
初期化に失敗すると、SDK は fail を通じて外側のエラーコード(例:data.code === 1003)を返します。data.content がオブジェクトの場合、data.content.code はサーバーの具体的なエラーコードで、data.content.desc はサーバーから提供された説明です(存在する場合)。
初期化検証とサービスエラー
| content.code | 意味 | 対処方法 |
|---|---|---|
| 4000 | 初期化パラメーターが無効 | AppKey、user_str、認証パラメーターが揃っているか確認してください。SDK が取得した認証データを使用し、手動で変更しないでください。 |
| 4003 | 認証署名の有効期限切れ、またはタイムスタンプが有効範囲外 | 認証データを再取得して初期化してください。データを生成するサーバーの時計を確認し、タイムスタンプとサーバーの現在時刻との差が30分以内になるようにしてください。 |
| 4005 | 署名検証に失敗 | AppKey と認証データが対応しているか確認してください。独自の認証サービスを使用する場合は、署名アルゴリズムとキー設定を確認してください。 |
| 4006 | アプリケーションが存在しない | AppKey、アプリケーションが削除されていないか、接続先がアプリケーションのデータセンターと一致するかを確認してください。 |
| 4008 | アプリケーションの WebPush VIP サービスの有効期限が切れ、サーバーが初期化を拒否 | 対象 AppKey の WebPush プランを確認し、更新してサービスを復旧した後に再初期化してください。コンソールで有効と表示される場合は、テクニカルサポートに AppKey の利用権限の確認を依頼してください。 |
| 5000 | サーバー内部エラー | 時間をおいて再試行してください。継続する場合は、AppKey、発生時刻、エラーの全情報を添えてテクニカルサポートに連絡してください。 |
| 5001 | サーバーがビジー、または登録結果の待機がタイムアウト | 時間をおいて再試行し、短時間に初期化を繰り返さないでください。継続する場合はテクニカルサポートに連絡してください。 |
例えば data.code === 1003 かつ data.content.code === 4008 は、VIP サービスの期限切れによる初期化失敗を示します。外側の code と content 内の具体的な原因の両方を確認してください。
登録サービスからそのまま返されるエラーコード
初期化時にユーザー登録が必要な場合、サーバーは登録サービスのコードもそのまま返します。以下はサーバーに保持されている互換性用のマッピングです。実際の応答は登録サービスのバージョンに依存します。
| content.code | 意味 | 対処方法 |
|---|---|---|
| 11 | サーバー内部エラー | 時間をおいて再試行し、継続する場合はテクニカルサポートに連絡してください。 |
| 999 | パラメーターが無効 | 初期化パラメーターと認証データを確認してください。 |
| 1002 | パラメーターが無効 | 初期化パラメーターと認証データを確認してください。 |
| 1005 | AppKey が見つからない | AppKey とアプリケーションのデータセンターを確認してください。 |
| 1006 | アプリケーションが存在しない | AppKey とアプリケーションの状態を確認してください。 |
| 1008 | アプリケーションが存在しない | AppKey とアプリケーションの状態を確認してください。 |
| 1009 | アプリケーションが現在のプラットフォームをサポートしていない | 対象 AppKey のアプリケーションで WebPush が設定されていることを確認してください。 |
| 1015 | 最大ユーザー数を超過 | テクニカルサポートにアプリケーションのユーザー数制限の確認を依頼してください。 |
| 4001 | AppKey が存在しない、または署名検証に失敗 | AppKey、認証データ、署名設定を確認してください。 |
| 4002 | ユーザーがログインしていない | SDK を再初期化し、継続する場合はテクニカルサポートに連絡してください。 |
| 4004 | 登録失敗 | エラーの全情報を保存し、時間をおいて再試行してください。継続する場合はテクニカルサポートに連絡してください。 |
例えば、外側の data.code === 1008 は地域制限を示しますが、外側が 1003 で内側が data.content.code === 1008 の場合はアプリケーションが存在しないことを示します。
認証失敗の詳細
認証 API が失敗すると、SDK は応答の message を文字列の data.content に格納します。API の元の code は content.code として返されません。以下の元のコードは、ブラウザーの開発者ツールで認証リクエスト(/v1/auth)の応答を確認してください。
| 認証 API の元の code | SDK コールバックの data.code | 意味と対処方法 |
|---|---|---|
| 400 | 1007 | 業務検証に失敗。APPKEY_NOT_FOUND は AppKey が見つからないことを示します。連携ドメインの未設定、Origin ヘッダーの欠落、リクエスト元ドメインとアプリケーション設定の不一致も考えられるため、content の説明を確認してください。Chrome 拡張機能の場合は拡張機能 ID の設定も確認してください。 |
| 2002 | 1007 | サーバー内部エラー。コールバックの content は inner err です。時間をおいて再試行し、継続する場合はテクニカルサポートに連絡してください。 |
| 2003 | 1007 | パラメーターが無効。コールバックの content は param invalid です。AppKey と user_str が渡されているか確認してください。 |
| 7017 | 1008 | 地域アクセス制限。コールバックの content は REGION_RESTRICTED です。テクニカルサポートにアカウントの地域アクセス制限の確認を依頼してください。 |
購読失効通知
ブラウザーのプッシュ購読が失効すると、サーバーは WebSocket の expired コマンドで 4107(subscribe expired)を送信します。これは初期化後のシステム通知であり、初期化の fail コールバックのエラーとしては返されません。SDK の mtPush.onExpired リスナーが通知を受け取りますが、そのコールバックにエラーコードは渡されません。










