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");
        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 を返します。

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 ガイド をご覧ください。