Android SDK API

SDK インターフェースの説明

• MTMAApi、MA 機能のすべてのインターフェイスが含まれています。

呼び出し前の注意事項

• start は、ホスト アプリケーションのメイン プロセスでのみ呼び出すことができます。
• 初期化前に設定できる構成インターフェイスを除き、他の MA ビジネス API は初期化が成功した後にのみ呼び出すことができます。
• すべての MA 外部 API はメインプロセスで呼び出すことを推奨します。非メインプロセスはメインプロセスの初期化状態を共有せず、呼び出しはメインプロセスに転送されません。 ・ メインプロセス以外が業務APIを呼び出した場合、コールバックありのインターフェースはCODE_START_FAIL (-2)、getEuid()、getMaRid()がnull値を返し、コールバックなしのビジネスインターフェースは実行されません。
• configDebugMode、setCollectControl、setReportInterval、setMaxEventCacheCount、および setNoActiveSessionEndDurationTime はインプロセス構成です。非メインプロセスでこれらを呼び出しても、メインプロセス MA の構成は変更されません。

SDK バージョンを取得する

サポートされているバージョン

サポートされる開始バージョン: 5.5.0

フィールド定義

• MTMAApi.SDK_VERSION_CODE: MA SDK デジタル バージョン番号。
• MTMAApi.SDK_VERSION_NAME: MA SDK 文字列のバージョン番号。

              
              int versionCode = MTMAApi.SDK_VERSION_CODE;
String versionName = MTMAApi.SDK_VERSION_NAME;

            

デバッグモードを設定する

サポートされているバージョン

サポートされる開始バージョン: 5.5.0

インターフェース定義

• configDebugMode(boolean enable)
  • MA SDK デバッグ ログを有効または無効にします。
  • startを呼び出す前に設定することをお勧めします。リリースバージョンではオフにすることをお勧めします。

              
              MTMAApi.configDebugMode(true);

            

MA機能を有効にする

サポートされているバージョン

サポートされる開始バージョン: 5.5.0

インターフェース定義

• start(MTMAConfig config, MTMAInitResultCallback callback)
  • インターフェースの説明: MA AppKey を使用して、MA SDK の独立バージョンを初期化します。
  • config: 初期構成。
    • MTMAConfig(String appKey): MA AppKey を設定します。
    • MTMAConfig(String appKey, UserIdentity userIdentity): MA AppKey とユーザー ID を同時に設定します。
  • callback: 初期化結果のコールバック。
  • MTMAInitResult：
    • isSuccess(): 初期化が成功したかどうか。
    • getCode(): 結果コード、0 は成功を示します。
    • getMessage(): 結果の説明。
    • getEuid(): 初期化が成功した後に取得された EUID。
    • getMaRid(): 初期化が成功した後に MA RID を取得しました。

呼び出し例

              
              MTMAConfig config = new MTMAConfig("your MA AppKey");
MTMAApi.getInstance(this).start(config, new MTMAInitResultCallback() {
    @Override
    public void onResult(MTMAInitResult result) {
        if (result.isSuccess()) {
            String euid = result.getEuid();
            String maRid = result.getMaRid();
        } else {
            int code = result.getCode();
            String message = result.getMessage();
        }
    }
});

            

実行時に AppKey を切り替える

最後の初期化コールバックが完了した後、新しい MTMAConfig を使用して start を再度呼び出すことができます。切り替え中は、他の MA ビジネス API が一時的に利用できなくなります。新しい AppKey の初期化が失敗した場合、古い AppKey への自動フォールバックはありません。

非推奨のインターフェイス

5.5.0 以降、次のインターフェイスは非推奨になります。

• start(CallBack callBack)
• start(UserIdentity userIdentity, CallBack callBack)

代わりに start(MTMAConfig config, MTMAInitResultCallback callback) を使用してください。

ユーザーIDを設定する

ユーザーがログインし、ユーザーに一致する EUID を取得するために関連情報を提供するときに、このインターフェイスを設定することをお勧めします

サポートされているバージョン

サポートされる開始バージョン: 5.0.0

インターフェース定義

• _setUserIdentity(UserIdentity userIdentity, CallBack callBack) _
  • インターフェースの説明: ・ユーザー会員カード番号などのユーザー識別情報を設定します。
  • パラメータの説明:
    • userIdentity: 発信者識別
      • setUserId(String userId): 先頭と末尾のスペースを削除した後は空にすることはできません。Unicode 文字は 255 文字までです。 0、null、undefined、nan はできません (大文字と小文字は無視されます)
      • setAnonymousId(String anonymousId): 先頭と末尾のスペースを削除した後は空にすることはできません (Unicode 文字は 256 文字まで)
      • setEmail(String email): 空にすることはできません。Unicode 文字は 256 文字までです。 @ を 1 つだけ含める必要があり、含めることができます。@ の前後を空にすることはできず、スペース、改行、タブを含めることはできません。 5.5.0 以降でサポートされる
      • setPhone(String phone): + で始まる E.164 形式に準拠する必要があり、国コードの最初の桁は 1 ～ 9 で、その後に 1 ～ 14 桁が含まれます。 5.5.0 以降でサポートされる
    • callBack: インターフェースのコールバック
  • 返品の説明:
    XXQPH0012QXZ
    • コード: 戻りコード、0 は成功を表し、-1 は失敗を表します。詳細については、メッセージ パラメーターの説明を参照してください。

呼び出し例

              
                              UserIdentity userIdentity = new UserIdentity();
                userIdentity.setUserId("your_user_id");
                userIdentity.setAnonymousId("your_anonymous_id");
                userIdentity.setEmail("user@example.com");
                userIdentity.setPhone("+8613800138000");
                MTMAApi.getInstance(this).setUserIdentity(userIdentity, new CallBack() {
                    @Override
                    public void onCallBack(int code, String message) {
                        MTCommonLog.e(TAG, "setUserIdentity code:" + code);
                        MTCommonLog.e(TAG, "setUserIdentity message:" + message);
                    }
                });

            

ユーザー ID フィールドの検証が失敗した場合、ネットワーク リクエストは送信されず、コールバックを通じて code = -3 が返されます。

ユーザーの連絡先情報を設定する

ユーザーの連絡先情報が変更された場合、このインターフェースを使用してユーザーの「連絡先情報」を更新できます。

サポートされているバージョン

サポートされる開始バージョン: 5.0.0

インターフェース定義

• setUserContact(JSONObject contacts, CallBack callBack)
  • インターフェースの説明: ・ユーザーの「連絡先」を設定します。
  • パラメータの説明:
    • 連絡先: 複数の連絡方法を設定します。 Key は連絡方法の名前、value は連絡方法の値です。現在、電子メール、携帯電話、固定電話、および whatsapp_phone の 4 つの連絡方法がサポートされています。
    • callBack: インターフェースのコールバック
  • 返品の説明:
    XXQPH0001QXZ
    • コード: 戻りコード、0 は成功を表し、-1 は失敗を表します。詳細については、メッセージ パラメーターの説明を参照してください。
    • メッセージ: 理由の説明

呼び出し例

              
                              JSONObject contacts = new JSONObject();
                try {
                    contacts.put("key1", "cc");
                    contacts.put("key2", "dd");
                } catch (JSONException e) {
                    e.printStackTrace();
                }
                MTMAApi.getInstance(this).setUserContact(contacts, new CallBack() {
                    @Override
                    public void onCallBack(int code, String message) {
                        Log.e(TAG, "setUserContact code:" + code);
                        Log.e(TAG, "setUserContact message:" + message);
                    }
                });

            

EUID を取得する

サポートされているバージョン

サポートされる開始バージョン: 5.0.0

インターフェース定義

• getEuid()
  • インターフェースの説明:
    • ユーザーの一意の ID を表す EUID を取得します。初期化が成功した場合は現在値のみが返され、それ以外の場合は null 値が返されます。

呼び出し例

              
              MTMAApi.getInstance(this).getEuid();

            

MA RID を取得する

サポートされているバージョン

サポートされる開始バージョン: 5.5.0

インターフェース定義

• getMaRid()
  • 現在の MA RID を取得します。初期化が成功した場合は現在値のみが返され、それ以外の場合は null 値が返されます。

              
              String maRid = MTMAApi.getInstance(this).getMaRid();

            

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

サポートされているバージョン

サポートされる開始バージョン: 5.5.0

インターフェース定義

• setChannelValue(long channelId, List values, CallBack callBack)
  • インターフェースの説明: チャネルの連絡先 ID を設定します。 AppPush チャネルは SDK によって自動的にバインドされるため、このインターフェイス設定を呼び出す必要はありません。
  • パラメータの説明:
    • channelId: MA コンソールで構成されたサードパーティのプッシュ チャネル ID は、0 より大きい必要があります。
    • values: チャネル コンタクト ID (RID やトークンなど) の値リストを空にすることはできず、リスト要素を空にすることもできません。
    • callBack: 結果コールバック、code == 0 は成功を示します。

              
              List<String> values = Collections.singletonList("push rid or token");
MTMAApi.getInstance(this).setChannelValue(136L, values, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
        // code == 0 means success
    }
});

            

レポート データ間隔を設定する

これは setMaxEventCacheCount インターフェイスとともに有効になり、いずれかの条件が満たされる限り報告されます。

サポートされているバージョン

サポートされる開始バージョン: 5.0.0

インターフェース定義

• setReportInterval(int interval)
  • インターフェースの説明:
    • レポートデータの間隔を設定します。このインターフェイスが呼び出されない場合、デフォルトではイベント データを報告するのに 10 秒かかります。
    • レポート間隔メモリ キャッシュ。これを有効にするには、アプリケーションのライフ サイクルごとに呼び出す必要があります。
  • パラメータの説明
    • 間隔レポート間隔、単位は s (秒)

呼び出し例

              
                  MTMAApi.getInstance(this).setReportInterval(10);

            

イベントキャッシュの上限を設定する

setReportInterval インターフェースとともに有効となり、いずれかの条件が満たされる限りレポートされます。

サポートされているバージョン

サポートされる開始バージョン: 5.0.0

インターフェース定義

• setMaxEventCacheCount(int count)
  • インターフェースの説明:
    • イベント キャッシュの上限を設定します。デフォルトは 50 で、最大値は 500 を超えることはできません。
    • キャッシュ量を超えると、すべてのデータがレポートされます
  • パラメータの説明
    • count イベントキャッシュ項目数の上限

呼び出し例

              
                  MTMAApi.getInstance(this).setMaxEventCacheCount(50);

            

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

サポートされているバージョン

サポートされる開始バージョン: 5.0.0

インターフェース定義

• setNoActiveSessionEndDurationTime(int duration)
  • インターフェースの説明:
    • アプリがバックグラウンドに配置されると、セッション タイムアウトの計算が開始されます。設定した時間を超えると（デフォルトは 30 分）、セッションは終了します。
  • パラメータの説明 -duration タイムアウト期間、単位 s (秒)

呼び出し例

              
                  MTMAApi.getInstance(this).setNoActiveSessionEndDurationTime(5*60);

            

UTM 属性を設定する

サポートされているバージョン

サポートされる開始バージョン: 5.0.0

インターフェース定義

• setUtmProperties(UtmProperties utmProperties)
  • インターフェースの説明:
    • UTM属性を設定します。ユーザーがどの広告からアプリにアクセスするかを開発者が特定できる場合は、UTM 情報を設定することをお勧めします。イベントを報告するときにこのパラメータを渡します。
  • パラメータの説明:
    • utmProperties UTM プロパティ オブジェクト
    • • utm_source キャンペーン ソース
    • • utm_medium キャンペーン媒体
    • • utm_term キャンペーン期間
    • • utm_content キャンペーン コンテンツ
    • • utm_campaign キャンペーン名

呼び出し例

              
                              UtmProperties utmProperties = new UtmProperties();
                utmProperties.setUtmSource("your_utm_source");
                utmProperties.setUtmCampaign("your_utm_campaign");
                utmProperties.setUtmContent("your_utm_content");
                utmProperties.setUtmId("your_utm_id" );
                utmProperties.setUtmMedium("your_utm_medium");
                utmProperties.setUtmTerm("your_utm_term");
                MTMAApi.getInstance(this).setUtmProperties(utmProperties);

            

データ取得制御

サポートされているバージョン

サポートされる開始バージョン: 5.0.0

インターフェース定義

• setCollectControl(MTMACollectControl control)
  • インターフェースの説明:
    • 収集権限を設定します。特定のデータ収集をオン/オフする必要がある場合は、このインターフェイスを呼び出してください。
  • パラメータの説明:
    • control: 収集許可設定。明示的に設定されていないプロパティには、次のデフォルト値が使用されます。
      • setCarrier(boolean enable): オペレーター情報を収集するかどうか、デフォルトで有効
      • setMacAddress(boolean enable): MAC アドレスを収集するかどうか、デフォルトでは無効になっています
      • setGAID(boolean enable): GAID を収集するかどうか、デフォルトでは閉じられています
      • setOAID(boolean enable): OAID を収集するかどうか、デフォルトでは閉じられています
      • setAAID(boolean enable): AAID を収集するかどうか、デフォルトで閉じられています
      • setIMEI(boolean enable): IMEI を収集するかどうか。デフォルトではオフになっています。 Android 9 以下でのみサポートされているため、ホスト アプリケーションは READ_PHONE_STATE 権限を宣言して取得する必要があります。

呼び出し例

              
              try {
MTMACollectControl mtmaCollectControl = new MTMACollectControl();
        mtmaCollectControl.setCarrier(true);
        mtmaCollectControl.setMacAddress(true);
        mtmaCollectControl.setGAID(true);
        mtmaCollectControl.setOAID(true);
        mtmaCollectControl.setIMEI(true);
        mtmaCollectControl.setAAID(true);
    MTMAApi.getInstance(this).setCollectControl(mtmaCollectControl);
} catch (Throwable e) {e.printStackTrace();
}

            

ユーザー属性を設定する

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

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

• propertySet(final JSONObject properties, final CallBack callBack)
  • インターフェースの説明:
    • ユーザー属性値を一括上書き更新
    • ユーザーのメンバーシップ レベルなどの履歴データを含め、最新のレポート データのみが保存されます。
    • 値は、文字列、数値、ブール値、文字列配列、要素がすべて JSONObject である JSONObject、および JSONArray をサポートします。
  • パラメータの説明:
    • プロパティ: ユーザープロパティ
    • callBack: インターフェースのコールバック
  • 返品の説明:
    XXQPH0004QXZ
    • コード: 戻りコード、0 は成功を表し、-1 は失敗を表します。詳細については、エラー コードの説明を参照してください。
    • メッセージ: 理由の説明
  • 電話の例:

              
              try {JSONObject properties = new JSONObject();
    properties.put("your_property_name","your_property_value");
    properties.put("your_property_name 2","your_property_value 2");
    properties.put("your_property_name 3","your_property_value 3");
    MTMAApi.getInstance(this).propertySet(properties, new CallBack() {
        @Override
        public void onCallBack(int code, String message) {}});
} catch (Throwable e) {e.printStackTrace();
}

            

• propertySet(String property, Object value, CallBack callBack)
  • インターフェースの説明:
    • 1 回のオーバーライドでユーザー属性の値が更新されます
    • ユーザーのメンバーシップ レベルなどの履歴データを含め、最新のレポート データのみが保存されます。
    • 値タイプのルールはバッチ propertySet と一致します。
  • パラメータの説明:
    • プロパティ: ユーザープロパティ名
    • 値: ユーザー属性値
    • callBack: インターフェースのコールバック
  • 返品の説明:
    onCallBack(int code, String message)
    • コード: 戻りコード、0 は成功を表し、-1 は失敗を表します。詳細については、エラー コードの説明を参照してください。
    • メッセージ: 理由の説明
  • 電話の例:

              
              MTMAApi.getInstance(this).propertySet("your_property_name","your_property_value", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

ユーザー属性を累積的に更新する

• propertyIncrease(final Map<String, ? extends Number> properties, CallBack callBack)
  • インターフェースの説明:
    • ユーザー属性の値設定を蓄積し、一括リクエストを行う
    • 累積消費量など、報告されたすべてのデータを蓄積します。
    • このインターフェイスは、数値タイプのユーザー属性に対してのみ呼び出すことができます。それ以外の場合は無視されます。ユーザー属性が以前に存在しない場合、初期値は 0 として扱われます。
  • パラメータの説明:
    • プロパティ: ユーザープロパティ
    • callBack: インターフェースのコールバック
  • 返品の説明:
    XXQPH0001QXZ
    • コード: 戻りコード、0 は成功を表し、-1 は失敗を表します。詳細については、エラー コードの説明を参照してください。
    • メッセージ: 理由の説明
  • 電話の例:

              
              Map<String,Number> properties = new HashMap();
properties.put("your_property_name",1);
properties.put("your_property_name 2",2);
properties.put("your_property_name 3",3);
MTMAApi.getInstance(this).propertyIncrease(properties, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

• propertyIncrease(final String property, final Number value, CallBack callBack)
  • インターフェースの説明:
    • ユーザー属性値設定の蓄積、単一リクエスト
    • 累積消費量など、報告されたすべてのデータを蓄積します。
    • このインターフェイスは、数値タイプのユーザー属性に対してのみ呼び出すことができます。それ以外の場合は無視されます。ユーザー属性が以前に存在しない場合、初期値は 0 として扱われます。
  • パラメータの説明:
    • プロパティ: ユーザープロパティ名
    • 値: ユーザー属性値
    • callBack: インターフェースのコールバック
  • 返品の説明:
    XXQPH0001QXZ
    • コード: 戻りコード、0 は成功を表し、-1 は失敗を表します。詳細については、エラー コードの説明を参照してください。
    • メッセージ: 理由の説明
  • 電話の例:

              
              MTMAApi.getInstance(this).propertyIncrease("your_property_name",1, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

###ユーザー属性を追加する

• propertyAdd(final String property, final String value, CallBack callBack)
  • インターフェースの説明:
    • ユーザー属性の値を追加、単一リクエスト
    • 継続的に要素をコレクションに追加し、重複排除のために要素をデータベースに保存します。すでに ABC が存在する場合は、CD を追加すると、最終的に ABCD になります。
  • パラメータの説明:
    • プロパティ: ユーザープロパティ名
    • 値: ユーザー属性値
    • callBack: インターフェースのコールバック
  • 返品の説明:
    XXQPH0001QXZ
    • コード: 戻りコード、0 は成功を表し、-1 は失敗を表します。詳細については、エラー コードの説明を参照してください。
    • メッセージ: 理由の説明
  • 電話の例:

              
              MTMAApi.getInstance(this).propertyAdd("your_property_name","your_property_value", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

• propertyAdd(final String property, final Set values, CallBack callBack)
  • インターフェースの説明:
    • ユーザー属性の値を追加し、複数の値を一度に追加します
    • 継続的に要素をコレクションに追加し、重複排除のために要素をデータベースに保存します。すでに ABC が存在する場合は、CD を追加すると、最終的に ABCD になります。
  • パラメータの説明:
    • プロパティ: ユーザープロパティ名
    • 値: ユーザー属性値
    • callBack: インターフェースのコールバック
  • 返品の説明:
    XXQPH0001QXZ
    • コード: 戻りコード、0 は成功を表し、-1 は失敗を表します。詳細については、エラー コードの説明を参照してください。
    • メッセージ: 理由の説明
  • 電話の例:

              
              Set<String> properties = new HashSet<>();
properties.add("your_property_value");
properties.add("your_property_value 2");
properties.add("your_property_value 3");
MTMAApi.getInstance(this).propertyAdd("your_property_name",properties, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

object_array 要素を操作する

次のインターフェイスは 5.5.0 以降でサポートされており、object_array ユーザー属性にのみ使用されます。元の propertyAdd、propertyRemove は引き続き文字列配列に使用され、動作は変わりません。

• updateObjectArrayProperty(String property, String identifierKey, Object identifierValue, JSONObject values, CallBack callBack)
  • 一意の識別子に基づいてオブジェクト要素のサブフィールドを更新します。
  • identifierValue は文字列または限定された数値をサポートします。 values は識別フィールドを変更できません。
  • values の JSONObject.NULL を使用して、対応するサブフィールドを削除します。

              
              JSONObject values = new JSONObject().put("enabled", false);
MTMAApi.getInstance(this).updateObjectArrayProperty(
        "devices", "device_id", "device_1", values, callBack);

            

• addObjectArrayProperty(String property, JSONObject object, CallBack callBack)
  • null 以外のオブジェクト要素を object_array に追加します。

              
              JSONObject device = new JSONObject()
        .put("device_id", "device_2")
        .put("year", 2026);
MTMAApi.getInstance(this).addObjectArrayProperty("devices", device, callBack);

            

• removeObjectArrayProperty(String property, String identifierKey, Object identifierValue, CallBack callBack)
  • 一意の識別子に基づいてオブジェクト要素全体を削除します。

              
              MTMAApi.getInstance(this).removeObjectArrayProperty(
        "devices", "device_id", "device_2", callBack);

            

ユーザー属性を削除する

• propertyRemove(final String property, String values, final CallBack callBack)
  • インターフェースの説明:
    • ユーザー属性に対する値の操作を削除しました。
    • この値はコレクション要素であり、要素は重複排除処理のためにデータベースに保存されます。 ABCD がすでに存在する場合は、D を削除して、最終的に ABC になります。
  • パラメータの説明:
    • プロパティ: ユーザープロパティ名
    • 値: ユーザー属性値
    • callBack: インターフェースのコールバック
  • 返品の説明:
    XXQPH0001QXZ
    • コード: 戻りコード、0 は成功を表し、-1 は失敗を表します。詳細については、エラー コードの説明を参照してください。
    • メッセージ: 理由の説明
  • 電話の例:

              
              MTMAApi.getInstance(this).propertyRemove("your_property_name","your_property_value", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

• propertyRemove(final String property, Set values, final CallBack callBack)
  • インターフェースの説明:
    • ユーザー属性の値を削除し、複数の値を一度に削除します。
    • この値はコレクション要素であり、要素は重複排除処理のためにデータベースに保存されます。 ABCD がすでに存在する場合は、CD が削除され、最終的に AB になります。
  • パラメータの説明:
    • プロパティ: ユーザープロパティ名
    • 値: ユーザー属性値
    • callBack: インターフェースのコールバック
  • 返品の説明:
    XXQPH0001QXZ
    • コード: 戻りコード、0 は成功を表し、-1 は失敗を表します。詳細については、エラー コードの説明を参照してください。
    • メッセージ: 理由の説明
  • 電話の例:

              
              Set<String> properties = new HashSet<>();
properties.add("your_property_value");
properties.add("your_property_value 2");
properties.add("your_property_value 3");
MTMAApi.getInstance(this).propertyRemove("your_property_name",properties, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

ユーザー属性を削除する

サポートされているバージョン

サポートされる開始バージョン: 5.0.0

インターフェース定義

• propertyDelete(final String property, final CallBack callBack)
  • インターフェースの説明:
    • ユーザー属性のすべての値を削除します。
  • パラメータの説明:
    • プロパティ: ユーザープロパティ名
    • callBack: インターフェースのコールバック
  • 返品の説明:
    XXQPH0001QXZ
    • コード: 戻りコード、0 は成功を表し、-1 は失敗を表します。詳細については、エラー コードの説明を参照してください。
    • メッセージ: 理由の説明

呼び出し例

              
              MTMAApi.getInstance(this).propertyDelete("your_property_name", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

インシデントの報告

サポートされているバージョン

サポートされる開始バージョン: 5.0.0

インターフェース定義

• onEvent(String eventKey, JSONObject properties)
  • インターフェースの説明:
    • インシデントの報告
  • パラメータの説明: -eventKey: イベント名
    • プロパティ: イベントのプロパティ。キーはプロパティ名、値はプロパティの値です。

呼び出し例

              
              JSONObject properties = new JSONObject();
properties.put("key1","v1");
properties.put("key2","v2");
MTMAApi.getInstance(this).onEvent("your_event_name",properties );

            

エラーコード