Web SDK API
認証
開発者が初期化を実行する場合、必要な情報を渡す必要があります。このデータ構造は開発者サーバーによって生成され、ブラウザに返送され、開発者がブラウザに実行を許可する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,
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は成功を意味し、その他は失敗を意味します。[エラーコード](#error code)を参照してください |
| message | string | 結果の説明 |
| content | string | 登録に失敗した場合(1003)に失敗メッセージを返します |
呼び出し例
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オブジェクトのエラーコード:
| コード | メッセージ | 備考 |
|---|---|---|
| 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の初期化後に呼び出す必要があります。
プッシュメッセージ表示コールバック
インターフェース説明
初期化の前にメッセージリスナーを呼び出すことを推奨します。
呼び出し例
window.MTpushInterface.onMsgDisplay((msgData) => {});
パラメータ説明
通知メッセージコールバックパラメータmsgDataの説明:
{
engagelab_ntf_or_msg: number;
engagelab_appkey: string;
engagelab_passwd: string;
engagelab_uid: number;
engagelab_mesg_type: string;
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: string;
}
注:
アプリ内メッセージのHTML編集モードでは、コールバックパラメータ
titleとcontentは空の文字列です。Safariブラウザのシステムチャネルを介して配信されたメッセージは、表示コールバックを受信できません。
プッシュメッセージクリックコールバック
インターフェース説明
初期化の前にメッセージリスナーを呼び出すことを推奨します。
呼び出し例
window.MTpushInterface.onMsgClick((msgData) => {});
パラメータ説明
通知メッセージコールバックパラメータmsgDataの説明:
{
engagelab_ntf_or_msg: number;
engagelab_appkey: string;
engagelab_passwd: string;
engagelab_uid: number;
engagelab_mesg_type: string;
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ブラウザのシステムチャネルを介して配信されたメッセージは、クリックコールバックを受信できません。
エラーコード
| コード | メッセージ | 備考 |
|---|---|---|
| 0 | success | 呼び出し成功 |
| 1000 | unknown error | 不明なエラー |
| 1001 | initing , please try again later | 初期化中、後で再試行してください |
| 1002 | invalid config | 初期設定エラー |
| 1003 | init failed | 初期化に失敗しました、詳細についてはコンソールの出力を参照してください |
| 1004 | init timeout | 初期化タイムアウト |
| 1005 | network error | ネットワークエラー、ネットワークがないかwebsocketに接続できません |
| 1006 | baseUrl と reportUrl の取得に失敗しました | get-webaddr API リクエストが失敗しました。詳細については、コールバック内の content フィールドを参照してください |
| 1007 | authentication failed | 認証に失敗しました。詳細については、コールバック内の content フィールドを参照してください |
| 1008 | region restricted | リージョン制限 |










