Android SDK実装ガイド

この実装ガイドでは、Oracle Maxymiser Mobile Application Testingソリューション(MMTApp)をネイティブAndroidアプリに統合するためのステップを説明します。また、A/Bテスト・キャンペーンの作成方法についても説明します。このガイドでは、Android用のアプリの作成に慣れていることを前提としています。

ここでプラットフォームおよびリージョンに適したSDKパッケージをダウンロードします。

スタート・ガイド

テスト管理およびレポート・インタフェースにアクセスするには、Oracle Maxymiserユーザー・インタフェース・ログインが必要です。オンボーディング・プロセスの一部としてログイン資格証明を受信していない場合は、Oracle Maxymiserに連絡してください。Oracle Maxymiser UIにアクセスするための関連する認可資格証明を喜んで送信します。

APIの使用およびアプリとの統合のための前提条件:

  • Android SDKがインストールされた開発環境。
  • Java for Androidを使用する開発能力。

Androidバージョン別機能サポート:

Androidバージョン ストア更新のないアプローチ
ストア更新のないUIの変換		 手動アプローチ
意思決定フェッチ用のAPI
API16以降 サポート対象 サポート対象
API10 - API 15 サポートされていません(SDK非アクティブ) サポート対象
API 9以前 サポートされていません(SDK非アクティブ) サポートされていません(SDK非アクティブ)

統合ガイド

SDKを統合するには、次の手順に従ってください。

アプリの2つのバージョン、つまりサンドボックスが有効なバージョンと、本番用のバージョンを構築するようにすることをお薦めします。setSandboxコールとprintElementIdsコールは初期化ステップで明示的に定義されず、アプリ・テストの実行時に重要であるため、このようにすると有益です。

このドキュメントとともに配布されるMMTAppライブラリのzipファイルを探して抽出します。IDEを起動し、テストするAndroidアプリケーションでプロジェクトを開きます。

アプリのクラスパスにMMTApp.jarを追加します。

SDKでは、AndroidManifest.xmlに次の権限を追加する必要があります。

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

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

ネイティブ・アプリのテストは、次の3つの方法で作成できます。

  • JavaScriptタグを使用するOracle Maxymiserの標準Webテスト方法を使用する: これを使用して、アプリ・コンテナ(ハイブリッド・アプリ)内でモバイルWebページまたはHTMLをテストできます。
  • Oracle Maxymiser SDKを使用するApp Storeなしのアプローチを使用する: SDKを使用して、アプリのソース・コードを変更したり、App Storeを介して更新をリリースすることなく、キャンペーン・コンテンツをアプリに直接インジェクトできます(Apple UIKitを使用して構築されたiOSアプリおよびAndroid UIキット要素を使用して構築されたAndroidアプリで使用可能)。
  • 手動アプローチを使用する: このアプローチは、iOSアプリとAndroidアプリの両方で有効であり、意思決定およびレポート・エンジンとしてOracle Maxymiserを使用します。アプリのソース・コードで開発作業を行い、ユーザーに対して更新をリリースする必要がありますが、より複雑なテスト・バリアントを作成する必要もあります。Oracle Maxymiser SDKは、意思決定エンジンを提供し、結果をレポート・システムにフィードバックします。

使用する方法に応じて、次の手順に従ってSDKを初期化します。

ストア更新のないアプローチ

ストア更新のないアプローチは、ネイティブ・アプリケーション用のA/Bテストを構築する方法の1つで、ユーザー・エクスペリエンスのバリアントをリモートでアプリにインジェクトします。このアプローチを使用すると、リリース・サイクルが後に続くアプリ内のコード変更ではなく、Oracle Maxymiserからキャンペーンやバリアントの更新を公開できます。一方、手動アプローチでは、アプリにコーディングされ、一般リリースを介してユーザーにリリースされるバリアントを使用します。この場合、Oracle Maxymiserは意思決定およびレポート・エンジンとして使用されます。

重要: ストア更新のないアプローチは、API16以降でのみサポートされています。API15以前では、SDKでバリアント変換の適用やアクションのトラッキングは行われません。

SDKの初期化

アプリケーションの初期化中に、次のコードを使用してSDKを初期化します。

// Show Interstitial page
MMTApp.startWithOptions(application,
    MMTApp.Options.optionsForSite("myapp")
        .setRequestTimeout((3000)),
    new MMTApp.Handler() {
        @Override
        public void onStarted() {
        // Hide interstitial page and display Home page
        }
    });

myappをOracle Maxymiser UIのサイトの名前に置き換えます。

オプションで、タイムアウトや使用するOracle Maxymiser環境などの初期化パラメータを設定できます。

重要: 初期化されたハンドラでアプリケーションのホーム・ページを表示してください。SDKの初期化前に表示されるページでは、キャンペーンを実行できません。

キャンペーンの作成

これで、キャンペーンを作成する準備ができました。詳細は、サイト作成から稼働公開までのアプリ・テストのページを参照してください。

手動アプローチ

SDKの初期化

アプリケーションの初期化中に、次のコードを使用してSDKを初期化します。

MMTApi api = MMTApp.getApi(context, "myapp");
api.setSandbox(true);

myappをOracle Maxymiser UIのサイトの名前に置き換えます。

その後は最初に作成したAPIをMMTApp.getDefaultApi()で参照できるため、作成したAPIへの参照を保持する必要はありません。

ストア更新のないアプローチでSDKを初期化した場合、APIを初期化する必要はありません。

キャンペーンの作成

これで、キャンペーンを作成する準備ができました。詳細は、アプリ・テストのページを参照してください。

エクスペリエンスのフェッチ

次のコードでは、すべてのキャンペーンおよびそのバリアントをフェッチして、後で使用するためにキャッシュします。

// Show interstitial page
[[MMTApp defaultApi] fetchExperiences:^{
// Hide interstitial page and display Home page
}];

第1引数は、エクスペリエンスがフェッチされたときに呼び出すハンドラです。このハンドラはメイン・スレッドで呼び出されるため、UIをこのハンドラ内で更新すると安全です。

レイテンシにより、表示するバリアントの詳細を含むOracle Maxymiserからのレスポンスの受信に短い遅延が発生する可能性があります。したがって、インタースティシャル・ページや検索用語/ログイン入力ページなど、アプリ内でユーザーが自然に遅延を経験する可能性がある場所でエクスペリエンスをフェッチすることをお薦めします。アプリの起動時点でエクスペリエンスをフェッチすることをお薦めします。

コンテンツ変換

エクスペリエンスがフェッチされたら、それらを使用してコンテンツを変換できます。

コンテンツ変換を実装するには、2つの方法から選択できます。

バリアント名

アプリの意思決定ロジックをバリアント名に基づいて作成します。この場合、View要素のユーザー・エクスペリエンスのバリアントでは、次の例に示す形式を使用する必要があります。

バリアント名 バリアント・コンテンツ
デフォルト 空
Variant1 空
Variant2 空 
(vois)viewWillAppear:(BOOL)animated {
[super viewWillAppear: animated;
UIColor *color = nil;
NSString *variantName = [[[MMTApp defaultApi] getExperiences]
[getVariantNameForCampaign:@"Campaign" element:@"view"];
if ([@"Variant1"isEqualToString:variantName]) {
color = [UIColorgreenColor ];
}else if ([@"Variant2"isEqualToString:variantName]) {
color = [UIColorblueColor ];
}else{ 
}
self.view.backgroundColor= color; 
[MMTApp defaultApi] trackContentSeen:@"Campaign"];
}

重要: テストの停止またはパーソナライズ・ロジックの結果としてエクスペリエンスが変わる可能性があるため、UIがユーザーに表示されるたびにエクスペリエンスが適用されていることを確認してください。

環境

Oracle Maxymiser UIはサンドボックスと本番の2つの環境をサポートしています。

サンドボックス

サンドボックスは、キャンペーンが作成および構成される開発テスト環境です。アプリケーションに対するすべてのテストはサンドボックスで実行する必要があります。すべてのサンドボックス・トラフィックは事前定義済の会社IPから提供され、レポートまたは分析の目的で保持されません。

サンドボックス・モードでキャンペーンをテストする前に、サイトの会社IPリスト(Oracle Maxymiser UIのサイト管理オプションの下)にデバイスIPを追加してください。

品質管理(QC)テストのために特定のバリアントをアプリ内でプレビューする手順は、次のとおりです。

  1. Oracle Maxymiser UIの「Campaign Settings」→「Campaign Content」→「Elements & Variants」ページを使用して、すべてのバリアントの重みを0に設定します。
  2. プレビューするバリアントの重みを100に設定します。アプリケーションを実行し、変換が正しく適用されていること、および他のすべての機能が期待どおりに動作していることを確認します。
  3. ユーザー・エクスペリエンスのすべてのバリアントに対してこれらのステップを繰り返します。
  4. 必要なステージを完了して、構成されたすべてのアクションをトリガーします。
  5. アクション・ログ・レポートをチェックし、アクションの値および属性が正しくログに記録されていることを確認します。

ノート: サンドボックス・モードで収集されたデータは、Oracle Maxymiserのアナリティクス・レポートには表示されません。このモードはQCテストのためにのみ存在します。サービス・レベル合意(SLA)はサポートされず、レポートが使用できないため、サンドボックス環境にテストが接続されているユーザーにはアプリをリリースしないでください。

本番

本番は本番(稼働中ユーザー)トラフィックの処理に使用される環境です。

この環境から収集されたデータは、どのバリアントのパフォーマンスが最良かを判断する分析のためにレポート領域で使用できます(Oracle Maxymiser UIの「Analytics」タブを参照)。

MMTAppでは、次のように環境を切り替えることができます。

ストア更新のないアプローチ:

// Show interstitial page 
[MMTAppstartForSite: @"myapp"
    options: @{
    MMTAppOptionUseSandbox : @YES
        }
    handler: ^{
//Hide interstitial page and display Home page
}];

手動アプローチ:

#ifdef DEBUG
[api useSandbox:YES];
#endif

重要: サンドボックス環境に接続されたキャンペーンを含むエンド・ユーザーに対して、アプリをリリースしないでください。

APIリファレンス

MMTアプリ

クラスの概要

サイトのAPIを作成する機能を提供し、SDK構成のメソッドが含まれます。

Publicメソッド

public static MMTApi getDefaultApi()

setDefaultApi(api)で明示的に設定されたデフォルトのMMTApiオブジェクトまたはgetApi(context,site)で作成された最初のAPIオブジェクトを返し、

デフォルトのAPIを使用できない場合はnullを返します。

public static void setDefaultApi(MMTApi api)

デフォルトのAPIを設定します。

public static MMTApi getApi(Context context, String site)

指定したサイトに新規APIを作成します。

public static void setUserAttribute(Context context, String name, String value)

ユーザー属性を設定します。この名前のカスタム属性が存在することを確認してください。

public static void setUserAttributeDynamic(Context context, String name, MMTApp.AttributeValueResolver resolver)

動的ユーザー属性を設定します。この名前のカスタム属性が存在することを確認してください。

public static void setUserId(Context context, String id)

ユーザーIDを設定します。

public static void startWithOptions(Application application, MMTApp.Options options, MMTApp.Handler handler)

ストア更新のないアプローチ・モードでSDKを起動します。

public static void stop()

ストア更新のないアプローチでSDKをオフにします。手動アプローチは引き続き使用できます。

public static void applyOnActivity(Activity activity)

アクティビティに対してUI変換を強制します。ビューのレイアウトを動的に変更する(つまり、フラグメントの変更時)アクティビティに対してエクスペリエンスを適用するために使用する必要があります。

public static void setViewId(View view, String id)

ビューIDを設定します。

public static void setLogger(Logger logger)

SDKで使用するロガーを設定します。

public static void setLogLevel(Logger.LogLevel level)

ロギング・レベルを設定します。

public static void setPrintElementsIDs(boolean printIDs)

要素IDの出力を有効または無効にします。

MMTApp.AttributeValueResolver

インタフェースの概要

属性値を提供するために呼び出すコールバックのインタフェース定義。

Publicメソッド

String getAttributeValue()

属性値を返します。

MMTApp.Handler

インタフェースの概要

ストア更新のないアプローチ・モードでSDKを起動したときに呼び出すコールバックのインタフェース定義。

Publicメソッド

void onStarted()

ストア更新のないアプローチ・モードでSDKを起動したときに呼び出すコールバック・メソッド。

MMTApp.Options

クラスの概要

ストア更新のないアプローチのSDK起動オプションを保持するクラス。

Publicメソッド

public MMTApp.Options setGenerationsPage(String generationsPage)

エクスペリエンスのフェッチに使用するページを設定します。デフォルトでは、「Generations」ページが使用されます。

public MMTApp.Options setActionsPage(String actionsPage)

アクション・トラッキングに使用するページを設定します。デフォルトでは、「Actions」ページが使用されます。

public MMTApp.Options setSandbox(boolean sandbox)

サンドボックスの構成を使用するかどうかを指定します。デフォルトでは、本番構成が使用されます。

public MMTApp.Options setWiFiOnly(boolean wifiOnly)

ユーザーがWi-Fiネットワークに接続しているときにのみ新しいエクスペリエンスをフェッチできるかどうかを指定します。デフォルトでは、任意の使用可能なネットワークが使用されます。

public MMTApp.Options setRequestTimeout(int requestTimeout)

サーバーへのリクエストに費やすことができる最大時間をミリ秒単位で設定します。デフォルトは3秒です。この時間を超過すると、エクスペリエンスをフェッチする試行が停止し、前のユーザー・エクスペリエンスが選択されます。

MMTApi

インタフェースの概要

エクスペリエンスのフェッチおよびアクションのトラッキングに使用するインタフェース。

Publicメソッド

void setSandbox(boolean sandbox)

サンドボックスの構成を使用するかどうかを指定します。デフォルトでは、本番構成が使用されます。

void setWiFiOnly(boolean wifiOnly)

ユーザーがWi-Fiネットワークに接続しているときにのみ新しいエクスペリエンスをフェッチできるかどうかを指定します。デフォルトでは、任意の使用可能なネットワークが使用されます。

void setRequestTimeout(int requestTimeout)

サーバーへのリクエストに費やすことができる最大時間をミリ秒単位で設定します。デフォルトは3秒です。

この時間を超過すると、エクスペリエンスをフェッチする試行が停止し、前のユーザー・エクスペリエンスが選択されます。

void fetchExperiences(MMTApi.FetchExperiencesHandler handler)

「Generations」という名前のデフォルト・ページについて、Oracle Maxymiserプラットフォームから新しいエクスペリエンスをフェッチします。フェッチはバックグラウンド・スレッドで実行されます。

void fetchExperiences(MMTApi.FetchExperiencesHandler handler, String page)

指定されたページについて、Oracle Maxymiserプラットフォームから新しいエクスペリエンスをフェッチします。フェッチはバックグラウンド・スレッドで実行されます。

Experiences getExperiences()

コンテンツ変換に使用するフェッチ済エクスペリエンスを返します。エクスペリエンスがフェッチされていない場合はnullを返します。

void trackContentSeen(String campaign)

ユーザーがコンテンツを提供したことを確認するための特別なタイプのアクションをトラッキングします。

void trackAction(String action, int value, String attribute)

「Actions」という名前のデフォルト・ページのユーザー・アクションをトラッキングします。値は、金額や合計などの各種パラメータのトラッキング、およびアクションに関連する各種追加情報のトラッキング用属性に使用できます。

void trackAction(String action, int value, String attribute, String page)

指定されたページのユーザー処理をトラッキングします。値は、金額や合計などの各種パラメータのトラッキング、およびアクションに関連する各種追加情報のトラッキング用属性に使用できます。

MMTApi.FetchExperiencesHandler

インタフェースの概要

SDKが新しいエクスペリエンスをフェッチしたときに呼び出すコールバックのインタフェース定義。

Publicメソッド

void onExperiencesFetched()

SDKが新しいエクスペリエンスをフェッチしたときに呼び出すコールバック・メソッド。

Experiences

インタフェースの概要

フェッチされたエクスペリエンスについて、生成されたバリアントを取得するために使用するインタフェース。

Publicメソッド

String getVariantName(String campaign, String element)

キャンペーンの生成済バリアント名およびOracle Maxymiser UIのテスト構成に関連する要素を取得します。

キャンペーンの要素の生成済バリアントの名前を返します。

キャンペーンが開始されていない、キャンペーンが終了している、キャンペーンが一時停止されている、サイトが無効になっている場合は、nullを返します。このような状況では、デフォルト・コンテンツをレンダリングするプロセスを配置する必要があります。

ログ出力

インタフェースの概要

SDKからのメッセージをログに記録するために使用するインタフェース。このインタフェースの実装は、MMTAppクラスに指定できます。

Publicメソッド

void debug(String tag, String message)

ログ・レベルがデバッグのメッセージをログに記録します。

void info(String tag, String message)

ログ・レベルが情報のメッセージをログに記録します。

void warn(String tag, String message)

ログ・レベルが警告のメッセージをログに記録します。

void warn(String tag, String message, Throwable e);

ログ・レベルが警告のメッセージをログに記録します。

void error(String tag, String message)

ログ・レベルがエラーのメッセージをログに記録します。

void error(String tag, String message, Throwable e)

ログ・レベルがエラーのメッセージをログに記録します。

void print(String tag, String message)

ログ出力がオフの場合でも、ユーザー・リクエストに応じて技術情報を出力します。

システム制限

現在、Oracle Maxymiserモバイル・ライブラリには次のシステム制限があります。

  1. 各アプリは1つのOracle Maxymiserサイト・エンティティに接続できます。
  2. ユーザー・インタフェースには、Web固有の用語がいくつか含まれています。前述のガイドでは、サポートされている設定を示しています。Oracle Maxymiser UIのその他すべての設定は無視できます。不明な場合は、Oracle MaxymiserがキャンペーンQCプロセスを支援できます。
  3. MaxPredictとRecommendはサポートされていません。
  4. モバイル・アプリ・キャンペーンに使用できるユーザー属性は少数です。サポートされる属性のリストは、付録2を参照してください。
  5. 「Filter Action by Referrer URL」および「Filter Action by URL」パラメータは、モバイル・アプリ・テスト内ではサポートされていません。