Android MA機能連携ガイド

適用バージョン

この記事は、5.5.0 以降のバージョンの MA SDK の独立バージョンに適用されます。

5.5.0 以降、MA は AppPush に依存しなくなり、独立して統合および初期化できるようになりました。 MA AppKey と Push AppKey は互いに独立しており、同じでも異なっていても構いません。

Fusion バージョン 5.5.0 より前の統合方法については、「5.5.0 より前の統合ガイド」(/ja_JP/docs/marketing-automation/client-sdk-reference/android-sdk/integration-guide-before-5.5.0) を参照してください。

1. SDK をインポートする

手動インポート

リリース パッケージの mt-sdk-ma-5.5.0.aar をアプリケーション プロジェクトの libs ディレクトリに追加します。

              
              dependencies {
    implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
}

            

Maven インポート

              
              dependencies {
    implementation 'com.engagelab.plugin:oth_ma:5.5.0'
}

            

AppPush を同時に使用する場合は、AppPush ドキュメントに従って、engagelab メイン パッケージを導入してください。 MA のみを使用する場合は、AppPush メイン パッケージを導入する必要はありません。

2. 権限の設定

AndroidManifest.xml でネットワーク権限を宣言します。

              
              <uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

            

MA のスタンドアロン バージョンでは、ENGAGELAB_PRIVATES_APPKEY、ENGAGELAB_PRIVATES_CHANNEL、プッシュ サービス、またはプッシュ レシーバーの構成は必要ありません。 AppPush を同時に使用する場合も、AppPush 統合ドキュメントに従って対応する構成を完了する必要があります。

3. SDKの初期化

メインプロセスのApplication.onCreate()で初期化することを推奨します。 MA AppKey は初期化に使用され、AppPush の初期化や登録の成功を待つ必要はありません。

              
              import android.app.Application;

import com.engagelab.privates.push.oth.ma.api.MTMAApi;
import com.engagelab.privates.push.oth.ma.api.MTMAConfig;
import com.engagelab.privates.push.oth.ma.api.MTMAInitResult;
import com.engagelab.privates.push.oth.ma.api.MTMAInitResultCallback;

public class MainApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        MTMAApi.configDebugMode(true);
        MTMAConfig config = new MTMAConfig("your MA AppKey");
        // 任意（5.5.2 以降）：ユーザーの同意結果に応じて収集を制御する場合は、アプリが現在記録している同意結果を渡します。true で有効、false で無効、一度も設定していない場合はデフォルトで有効です
        // config.dataCollectionEnabled(enabled);
        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();
                }
            }
        });
    }
}

            

初期化手順

• MA AppKey が必要です。
• Android MA SDK は、ホスト アプリケーションのメイン プロセスでの初期化のみをサポートします。非メインプロセスで start を呼び出すと、コールバックを通じて失敗が返され、ネットワーク要求は開始されません。
• 初期化が成功する前は、初期化前の構成インターフェイスを除き、他の MA ビジネス API は使用できません。
• すべての MA 外部 API はメインプロセスで呼び出すことを推奨します。非メインプロセスはメインプロセスの初期化ステータスを共有せず、ビジネスコールはメインプロセスに転送されません。
• 初期化が成功した後、getEuid() および getMaRid() を通じて現在の値を取得することもできます。

実行時に MA AppKey を切り替える

同じプロセスは、実行時の MA AppKey の切り替えをサポートします。最後の初期化コールバックが完了した後、新しい AppKey を使用して start を再度呼び出してください。

              
              MTMAConfig newConfig = new MTMAConfig("new MA AppKey");
MTMAApi.getInstance(this).start(newConfig, callback);

            

切り替え中は、他の MA ビジネス API が一時的に利用できなくなります。新しい AppKey が正常に初期化されると、後続のイベントとユーザー データは新しい AppKey に属します。新しい AppKey の初期化に失敗した場合、SDK は自動的に古い AppKey にフォールバックしないため、有効な AppKey を使用して start を再度呼び出す必要があります。

初期化中にユーザー ID を設定します

              
              UserIdentity identity = new UserIdentity();
identity.setUserId("your user id");
identity.setAnonymousId("your anonymous id");
identity.setEmail("user@example.com");
identity.setPhone("+8613800138000");

MTMAConfig config = new MTMAConfig("your MA AppKey", identity);
MTMAApi.getInstance(this).start(config, callback);

            

このうち、setEmail と setPhone はバージョン 5.5.0 からサポートされます。

ユーザー識別子フィールドの規則：前後の空白を除去した後、user_id は空であってはならず、255 Unicode 文字以内で、0、null、undefined、nan のいずれとも一致してはなりません（大文字と小文字は区別しません）。前後の空白を除去した後、anonymous_id は空であってはならず、256 Unicode 文字以内である必要があります。email は空であってはならず、256 Unicode 文字以内で、空でない文字列の間に @ をちょうど1つ含み、空白、改行、タブを含めることはできません。phone は E.164 形式を使用し、+ で始まり、国番号の先頭は1～9、その後に1～14桁の数字が続く必要があります。検証に失敗した場合、SDK は識別子リクエストを送信せず、コールバックで code = -3 を返します。

任意：ユーザーの同意に応じて収集を制御する

ユーザーの同意結果に応じて収集を制御する必要がある場合は、データ収集スイッチを使用できます。不要な場合は変更の必要はなく、デフォルトで有効となり、アップグレード前と同じ動作になります。この機能は MA SDK 5.5.2 以降で提供されます。

スイッチは MA AppKey ごとに保存されます。初期化時には、ユーザーの同意状態に応じて dataCollectionEnabled に動的に値を渡してください。設定をハードコードすると、初期化のたびに状態がその固定値にリセットされてしまいます。実行中にユーザーが選択を変更した場合は、初期化成功後に setDataCollectionEnabled を呼び出してください。いずれもメインプロセスで実行します：

              
              // enabled は、ユーザーの同意結果に基づいてアプリが決定するスイッチの状態です
MTMAConfig config = new MTMAConfig(maAppKey);
config.dataCollectionEnabled(enabled);
MTMAApi.getInstance(this).start(config, initCallback);

// 実行中にユーザーが選択を変更した場合
MTMAApi.getInstance(this).setDataCollectionEnabled(enabled);

            

導入時の注意事項：

• 無効期間中は、イベント、ユーザー属性、UTM、デバイス情報の収集と送信が停止します。初期化、ユーザー識別子、連絡先、プッシュチャネルは通常どおり利用でき、SDK はこれらに必要なリクエストを引き続き送信します。
• 有効から無効に切り替えると、SDK は切り替え前に生成されたデータを直ちに 1 回送信します。失敗してもリトライせず、その後ローカルキャッシュを消去します。
• config.dataCollectionEnabled を呼び出す場合は true または false を渡す必要があり、start のたびに適用されます。前回の状態と異なる場合、今回の起動は新しい状態でそのまま初期化されます。起動済みの状態で再度 start を呼び出して状態を変更した場合は、無効化または有効化の処理が 1 回実行されます。
• 再度有効にすると SDK は自動的に収集を再開します。復帰完了前に呼び出したイベント、ユーザー属性、UTM は保持されません。

インターフェースのパラメータ、無効期間中の各インターフェースの動作、エラーコードについては、API ガイドのデータ収集スイッチを参照してください。

4. AppPush を同時に使用する

MA コンソールでモバイル データ ソースを構成する場合は、同時に AppPush を使用することを選択し、実際に接続されている AppPush アプリケーションを選択してください。 AppPush を初期化するときは、選択したアプリの AppKey を使用します。

MA と AppPush は個別に初期化されるため、固定順序は必要ありません。 AppPush が正常に登録され、Push RID が取得されると、MA SDK は自動的に AppPush チャネルをバインドします。

AppPush が統合されていないか、登録されていない場合、またはチャネル バインディングが失敗しても、MA の初期化、イベント収集、レポートには影響しません。

注: MA RID と AppPush RID は、2 つの独立したデバイス識別子です。これらはそれぞれ対応する SDK を通じて取得して使用し、一方を他方として使用しないでください。

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

サードパーティのプッシュ チャネルのチャネル コンタクト ID を設定する必要がある場合は、MA が正常に初期化された後に呼び出してください。

              
              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
    }
});

            

• channelId: MA コンソールで構成されたサードパーティのプッシュ チャネル ID は 0 より大きい必要があります。
• values: チャネル コンタクト ID (RID やトークンなど) の値リストを空にすることはできず、リスト要素を空にすることもできません。
• チャネル コンタクト ID が変更された後、インターフェイス更新を再度呼び出す必要があります。
• このインターフェイスは、サードパーティのプッシュ チャネルの連絡先 ID を設定するために使用されます。 AppPush チャネルは SDK によって自動的にバインドされます。

6. 旧バージョンのアップグレード手順

• 5.5.0 にアップグレードした後は、MTMAConfig を使用して MA AppKey を明示的に渡す必要があります。
• AppPush の長い接続や登録の成功を待って MA start を呼び出す必要はなくなりました。
• start(CallBack) および start(UserIdentity, CallBack) は廃止されました。スタンドアロン バージョンには start(MTMAConfig, MTMAInitResultCallback) を使用してください。
• もともと AppPush と MA を同時に使用していたアプリケーションは引き続き AppPush を統合できますが、個別に初期化する必要があります。
• MA RID と AppPush RID は 2 つの独立したデバイス識別子です。これらはそれぞれ対応する SDK を通じて取得して使用し、一方を他方として使用しないでください。

その他のビジネス インターフェイスについては、API ガイド をご覧ください。