API ガイド

ユーザー識別を設定する

対応バージョン

email、phone 識別の対応開始バージョン：2.1.0

インターフェース定義

• identifyAccount(user);
  • インターフェース説明：
    • ユーザー識別を設定します。例えば、ユーザーの会員カード番号など。
  • パラメーター説明
    • identity：ユーザー識別 ID。Key は user_id、anonymous_id、email、phone の 4 つの値をサポートします。少なくとも 1 つを指定してください。すべてを指定する必要はありません
    • completion：コールバック
  • ユーザー識別のルール
    • user_id：前後の空白を除去した後に空でないこと、最長 255 文字、0、null、undefined、nan（大文字小文字を区別しない）は不可
    • anonymous_id：前後の空白を除去した後に空でないこと、最長 256 文字
    • email：ユーザーのメールアドレス。前後の空白を除去した後に空でないこと、最長 256 文字、user@example.com のような有効なメール形式である必要があります
    • phone：ユーザーの電話番号。+8613800000000 のように、国または地域コードを含む E.164 形式である必要があります
    • いずれかのフィールドがルールに適合しない場合、今回の呼び出しではリクエストを送信せず、completion は -1 を返し、message に具体的な理由が入ります

呼び出し例

              
                  let user = {completion: (code, message)=>{}, identity:{"user_id":"value","anonymous_id":"value","email":"user@example.com","phone":"+8613800000000"}}
    window.MAInterface.identifyAccount(user)

            

ここでの email、phone はユーザー身元のマッチングに使用され、新しい EUID が返される場合があります。「ユーザー連絡先を設定する」（setUserContact）で設定する連絡先とは相互に代替できません。

EUID を取得する

インターフェース定義

• + EUID()
  • インターフェース説明：
    • EngageLab MA の EUID を取得します

呼び出し例

              
                  window.MAInterface.EUID((code,euid)=>{
        console.log(code, euid)
    })

            

ユーザー連絡先を設定する

インターフェース定義

• setUserContact(user)
  • インターフェース説明：
    • 複数の連絡先の値を同時に設定できます。Key は連絡先の名称、value は連絡先の値です。現在、email、mobile_phone、landline_phone、whatsapp_phone の 4 種類の連絡先をサポートしています
  • パラメーター説明
    • contacts：ユーザーの連絡先
    • completion：コールバック

呼び出し例

              
                    let user = {
          completion: (code, message)=>{ },
          contacts: {}
       }
      user.contacts["連絡先の名称"] = "連絡先の値"   //例：mobile_phone=18800000000
      window.MAInterface.setUserContact(user)

            

チャネル連絡先 ID を設定する

対応バージョン

対応開始バージョン：2.1.0

インターフェース定義

• setChannelValue(channelId, values, completion)
  • インターフェース説明：
    • MA コンソールで設定した Push チャネル（WebPush、サードパーティ Push など）に RID または Token を設定します。
    • SDK の初期化成功後に呼び出す必要があります。そうでない場合、completion は -1 を返します。
    • RID または Token が変化した場合は、再度インターフェースを呼び出して更新する必要があります。
  • パラメーター説明
    • channelId：MA コンソールで設定した Push チャネル ID。0 より大きい整数である必要があります
    • values：チャネル連絡先 ID の値の配列（RID や Token など）。空にできず、配列の要素も空文字列にできません
    • completion：コールバック。code が 0 の場合は成功を示します

呼び出し例

              
                 window.MAInterface.setChannelValue(136, ["push rid or token"], (code, message)=>{})

            

データ収集スイッチ

対応バージョン

対応開始バージョン：2.2.0

機能説明

アプリケーションは、ユーザーの同意結果に応じて MA SDK のデータ収集を有効または無効にします。ユーザーが同意を拒否または撤回した後は行動データを報告してはならないというコンプライアンス要件を満たすために使用します。

• 無効：イベント、ユーザー属性、UTM、デバイス情報の生成・キャッシュ・報告を停止します。初期化、EUID/RID の取得、ユーザー識別の設定、連絡先の設定、チャネル連絡先 ID の設定は通常どおり使用できます。
• 有効：収集を再開します。無効期間中のデータは補完送信されません。
• デフォルトで有効：未設定の場合はデフォルトで有効となり、アップグレード前の動作と一致します。
• ローカルに保存：状態はブラウザのローカル（localStorage）に保存され、更新やページの再オープン後も保持されます。サイトデータを消去するとデフォルトに戻ります。
• アプリケーションがスイッチを決定：SDK はユーザーの所在地域を判定せず、同意ウィンドウも表示せず、同意管理プラットフォーム（CMP）も読み取りません。

インターフェース定義

• init({ dataCollectionEnabled })

  • インターフェース説明：初期化時に初回起動のスイッチ状態を設定します。
  • パラメーター説明：true は有効、false は無効。渡さない場合はデフォルトで有効。

• setDataCollectionEnabled(enabled, completion)

  • インターフェース説明：データ収集を有効または無効にします。即時に反映され、ローカルに保存されます。
  • パラメーター説明：
    • enabled：true は有効、false は無効
    • completion：コールバック。code が 0 の場合は成功を示します。パラメーターがブール値でない場合は -1 を返します
  • 呼び出し説明：
    • 設定する値が現在の状態と同じ場合は切り替え処理は発生しないため、ページ読み込みごとにユーザーの選択を同期しても追加の影響はありません。
    • 有効から無効に切り替えると、SDK は切り替え前に発生したデータ（今回のセッションの終了イベントを含む）を直ちに 1 回送信しようとします。失敗しても再試行せず、その後ローカルキャッシュを消去します。
    • 無効から有効に切り替えると、SDK はデバイス情報を報告し、新しいセッションを開始します（el_session_start と現在のページの el_page_view を報告）。
    • 無効期間中は WebPush プッシュクリックのコンバージョン帰属は集計されなくなります。

• isDataCollectionEnabled()

  • インターフェース説明：現在のスイッチ状態を返します。ローカルの状態のみを読み取り、ネットワークリクエストは発生しません。
  • 戻り値説明：true は有効、false は無効。保存されたことがない場合は true を返します。戻り値は SDK のスイッチ状態を示すものであり、ユーザーが同意済みであることを意味するものではありません。

無効期間中の各インターフェースの動作

呼び出し例

              
                // 初期化時は、ユーザーの同意状態に応じてdataCollectionEnabledに動的に値を渡してください。設定を固定値で書かないでください。初期化のたびに状態が固定値にリセットされてしまいます
  window.MAInterface.init({
    appKey: "your appKey",
    dataCollectionEnabled: false,
    completion: (code, msg) => {}
  })

  // ユーザーが同意した後
  window.MAInterface.setDataCollectionEnabled(true, (code, msg) => {})

  // ユーザーが同意を撤回した後
  window.MAInterface.setDataCollectionEnabled(false, (code, msg) => {})

  // 照会
  const enabled = window.MAInterface.isDataCollectionEnabled()

            

UTM 属性を設定する

インターフェース定義

• setUtmProperties(attrs:any)
  • インターフェース説明：
    • UTM 属性は標準のイベント属性です。開発者がユーザーがどの広告から App に遷移してきたかを識別できる場合は、UTM 情報を設定することを推奨します。イベント報告時にこのパラメーターを送信します。現在設定可能な UTM 属性は以下の通りです：
      • utm_source 広告キャンペーンの出所
      • utm_medium 広告キャンペーンの媒体
      • utm_term 広告キャンペーンのキーワード
      • utm_content 広告キャンペーンの内容
      • utm_campaign 広告キャンペーンの名称
      • utm_id 広告キャンペーンの ID

呼び出し例

              
                 window.MAInterface.setUtmProperties({"utm_source":"value1"})

            

ユーザー属性を設定する

ユーザー属性の値を設定します。ユーザー属性が存在しない場合、バックエンドで自動的に作成されます。

ユーザー属性を上書きして更新する

• setProperty(user, completion)
  • インターフェース説明：
    • ユーザー属性の値を上書きして更新します
    • 最新の報告データのみを保存し、履歴データを上書きします。例えば、ユーザーの会員ランクなど。
    • これらのユーザー属性の内容は 1 つの object に保存されます。その中の key はユーザー属性の名称で、string である必要があります。Value はユーザー属性の内容で、string、number、Array、object、object_array 型をサポートします。
    • Array 型の value は、現在その要素が string のもののみサポートします。要素がすべて object の配列は object_array として処理され、object とその他の型が混在する配列は無効です。
    • あるユーザー属性が以前から存在していた場合、今回上書きされます。存在しない場合は作成されます。object と object_array の更新ルールは後述を参照してください。
  • 呼び出し例：

              
                 window.MAInterface.setProperty({key:"value"}, (code, message)=>{})

            

object / object_array のルール

対応開始バージョン：2.1.0

• object は空でないプレーンオブジェクトです。例：{ city: "Singapore", score: 100 }。object_array は要素がすべて空でないプレーンオブジェクトの配列です。
• サブフィールド名は空でない string である必要があり、. や $ を含めることはできません。サブフィールドの値は string、number、string 配列をサポートし、object や object_array をさらにネストすることはサポートしません。
• object はサブフィールドのマージセマンティクスを使用します。再度設定する際は今回渡したサブフィールドのみを更新し、渡していないサブフィールドは変更されません。サブフィールドの値に null を渡すと、そのサブフィールドを削除することを意味します。
• object_array は全体置換セマンティクスを使用します。再度設定する際は新しい配列で元の配列を全体的に置き換え、配列の順序を保持します。object_array を初めて作成する際は、空でないオブジェクト配列を渡してください。
• サブフィールドの型は MA コンソールにおけるそのユーザー属性の定義と一致している必要があります。一致しない場合はサーバー側から失敗が返されます。

              
                 window.MAInterface.setProperty({
       profile: { city: "Singapore", score: 100 },
       addresses: [
           { id: "home", city: "Singapore" },
           { id: "office", city: "Tokyo" }
       ]
   }, (code, message)=>{})

   // profile.scoreのみを更新し、profile.cityは変更されない
   window.MAInterface.setProperty({ profile: { score: 200 } }, (code, message)=>{})

            

ユーザー属性を増分更新する

• increaseProperty(user, completion)
  • インターフェース説明：
    • ユーザー属性の値に増分を設定します。
    • 複数の数値型ユーザー属性に数値を加算します。報告されたすべてのデータを累計します。例えば、累計消費金額など。
    • このインターフェースは number 型のユーザー属性に対してのみ呼び出すことができ、それ以外は無視されます。該当ユーザー属性が以前存在しなかった場合、初期値は 0 として処理されます。
  • 呼び出し例：

              
               window.MAInterface.increaseProperty({key:1}, (code, message)=>{})

            

ユーザー属性を追加する

• addProperty(key, content completion)
  • インターフェース説明：
    • ユーザー属性の値に追加を行います。
    • この集合の要素を継続的に追加できます。要素はデータベースへの保存時に重複排除処理されます。既に ABC が存在し、CD を追加すると、最終的に ABCD になります。例えば、ユーザーが「いいね」したニュースなど。
    • Array 型の属性にいくつかの値を追加します。この Array の要素は string である必要があり、そうでない場合は無視されます。また、append するユーザー属性が以前存在しなかった場合は、空の Array が初期化されます。
  • 呼び出し例：

              
               window.MAInterface.addProperty("key",["value1", "value2"], (code, message)=>{})

            

ユーザー属性値を削除する

• removeProperty(key, content completion)
  • インターフェース説明：
    • 配列型の属性の中の 1 つまたは複数の値を削除します。
    • Array 型の属性の中のいくつかの値を削除します。この Array の要素は string である必要があり、そうでない場合は無視されます。また、removeEventListAttrValue するユーザー属性が以前存在しなかった場合は、効果はありません。
  • 呼び出し例：

              
               window.MAInterface.removeProperty("key",["value1", "value2"], (code, message)=>{})

            

object_array 要素を操作する

対応バージョン

対応開始バージョン：2.1.0

以下の用法は object_array 型のユーザー属性のみに使用し、一意識別子のサブフィールドによって配列内の要素を特定します。addProperty、removeProperty に文字列配列を渡す場合は引き続き文字列配列に対して使用され、動作は変わりません。

• addProperty(key, object, completion)
  • インターフェース説明：
    • 第 2 パラメーターに（配列ではなく）単一の object を渡した場合、object_array の末尾に 1 つの要素を追加します。既存の要素には影響しません。
    • object は空でないオブジェクトである必要があり、サブフィールドのルールは object 型と同一です。object や object_array のネストはサポートしません。
    • この属性が MA コンソールで未定義の場合、サーバー側は object_array 型の属性を自動的に作成し、この要素を書き込みます。属性は定義済みだが現在のユーザーにまだ値がない場合は、この 1 つの要素で配列を作成します。
  • 呼び出し例：

              
               window.MAInterface.addProperty("addresses", { id: "school", city: "Osaka" }, (code, message)=>{})

            

• updateProperty(key, content, completion)
  • インターフェース説明：
    • 一意識別子のサブフィールドによって object_array 内の 1 つの要素を特定し、その要素のサブフィールドをマージ更新します。
    • content の構造は { $identifier_key, $identifier_value, $new_object } です：
      • $identifier_key：要素の特定に使用するサブフィールド名。このサブフィールドは MA コンソールで定義済みで、型が string または number である必要があります
      • $identifier_value：特定値。型は string または number です。複数の要素にマッチした場合は、マッチしたすべての要素に適用されます
      • $new_object：更新するサブフィールド。空でないオブジェクトである必要があり、$identifier_key に対応するサブフィールドを含めることはできません。渡していないサブフィールドは変更されず、サブフィールドの値に null を渡すとそのサブフィールドを削除することを意味します
    • 配列内にマッチする要素がない、またはサブフィールドが属性定義に適合しない場合、サーバー側は失敗を返し、他の要素は変更されません。複数の要素にマッチする場合は、マッチしたすべての要素に対して同じ更新を実行します。
    • この属性が未定義の場合、サーバー側は失敗（55004）を返します。属性は定義済みだが現在のユーザーにまだこの属性値がない場合は、code=0 を返しますが変更は行われません。
  • 呼び出し例：

              
               // idがhomeの要素のcityをTokyoに更新し、zipサブフィールドを削除する
 window.MAInterface.updateProperty("addresses", {$identifier_key:"id", $identifier_value:"home", $new_object:{city:"Tokyo", zip:null}}, (code, message)=>{})

            

• removeProperty(key, content, completion)
  • インターフェース説明：
    • 第 2 パラメーターに { $identifier_key, $identifier_value } を渡した場合、object_array 内でマッチする要素全体を削除します（複数マッチした場合はすべて削除）。content にはこの 2 つのフィールドのみを含めることができます。
    • $identifier_key、$identifier_value の要件は updateProperty と同一です。
    • この属性が未定義の場合、サーバー側は失敗（55004）を返します。現在のユーザーにこの属性値がない、またはマッチする要素がない場合、サーバー側は今回のリクエストを無視して code=0 を返します。複数の要素にマッチする場合は、マッチしたすべての要素を削除します。
  • 呼び出し例：

              
               // idがofficeの要素を削除する
 window.MAInterface.removeProperty("addresses", {$identifier_key:"id", $identifier_value:"office"}, (code, message)=>{})

            

ユーザー属性を削除する

インターフェース定義

• deleteProperty(key, completion)
  • インターフェース説明：
    • あるユーザー属性のすべての value 内容を削除します。
    • このユーザー属性が以前存在しなかった場合は、そのまま無視されます。

呼び出し例

              
               window.MAInterface.deleteProperty("key", (code, message)=>{})

            

セッションタイムアウトを設定する

インターフェース定義

• setSessionTimeout(time)
  • インターフェース説明：
    • セッションタイムアウトを設定します。ページがバックグラウンドに置かれると、セッションタイムアウトの計算を開始し、設定された時間（デフォルトは 30 分）を超えると今回のセッションを終了します。

呼び出し例

              
               window.MAInterface.setSessionTimeout(60)

            

ページ滞在時間を設定する

インターフェース定義

• setPageStayTime(time)
  • インターフェース説明：
    • ページ滞在時間の長さを設定します。
    • ページにアクセスした後に計時を開始し、そのページに time 秒間滞在して離脱しなかった場合、そのイベントを報告します。
    • デフォルトでは 5 秒、30 秒、60 秒、2 分、5 分、10 分の 6 つのタイムポイントで報告します。開発者はこのインターフェースを呼び出して、さらに多くのタイムポイントを追加できます

呼び出し例

              
               window.MAInterface.setPageStayTime(60)

            

イベントを報告する

イベントが存在しない状態で直接報告した場合、バックエンドでそのイベントが自動的に作成されます

インターフェース定義

• onEvent(event)
  • インターフェース説明：
    • イベントを報告します
  • パラメーター説明
    • event：報告するイベント。name はイベント名、properties はイベント属性情報で、その中の Key は属性名、value は属性値です

呼び出し例

              
                 let event = {name:"name", properties:{key:"value"}}
    window.MAInterface.onEvent(event)