Android SDK

Android SDK実装ガイド

• 過去のバージョン履歴については、こちらのリリースノートをご確認下さい。
• Android SDKの実装には、最新のAndroid Studioを利用されることをお勧めします。
• Unityの実装手順については, こちらをご確認ください。
• ご質問がある方は、support@tenjin.comまでお問い合わせください。

目次

• 基本実装
  • Google PlayまたはAmazonストア
    • パーミッション
    • Android広告ID (AAID)
    • アプリストア設定
    • SDK初期化
  • その他のAndroidストア
    • パーミッション
    • Android広告ID (AAID)
    • OAID
      • MSA OAID
      • Huawei OAID
      • Huaweiインストールリファラ
    • アプリストア設定
    • SDK初期化
  • 難読化設定
• 追加実装
  • GDPR対応
    • CMPコンセント情報を使ったオプトイン/アウト
  • アプリ内課金イベント
  • カスタムイベント
  • サーバ間インテグレーション
  • アプリサブバージョン
  • Live Opsキャンペーン
  • カスタマーユーザID
  • Analytics Installation ID
  • イベントのリトライ/キャッシュ
  • インプレッションレベル広告収益の実装
  • Google DMAパラメータ
• テスト

基本実装

マニュアルインストール

以下の「Android Studio」セクションに記載されている手順をご確認ください。

Maven

Mavenを使用する場合は、com.tenjin:android-sdk:VERSIONをGradleの依存関係に追加し、ソース リポジトリにまだ存在しない場合はmavenCentral()を追加してください。

Androidスタジオ

1. 最新のAndroid SDKをこちらよりダウンロードします。

2. Tenjin SDKをAndroid Studioプロジェクトに追加します。 Android Studioのプロジェクトナビゲータに移動します。プロジェクトナビゲータでオプション「プロジェクト」を選択します。 Android Studioプロジェクトの appモジュールの下にlibsフォルダーがあります。

3. ファイル tenjin.jarまたはtenjin.aarを libsフォルダに追加してください。
   
   4.Android Studioプロジェクトの appモジュールで、build.gradleファイルを選択し、依存関係ブロックの下に以下を追加します。

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

   デモプロジェクトtenjin-android-sdk-demoは、tenjin-android-sdkの実装サンプルです。

Google PlayまたはAmazonストア

Google PlayストアまたはAmazonストアでアプリを配布する場合には、次の初期設定を実装してください。

パーミッション

manifestファイルに下記のパーミッションを追加します。

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <!-- Required to get network connectivity (i.e. wifi vs. mobile) -->

2022年4月1日より、ターゲットAPIレベルが32(Android 13)のアプリでGoogle広告IDを取得するには、下記のパーミッションが必要となります。できるだけ早く下記パーミッションの追加をお願いいたします。 下記のパーミッションを使用するには、1.12.8以上のバージョンのAndroid SDKを使用する必要があります。

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

Android広告ID (AAID)とインストールリファラ

Android広告ID(AAID)とインストールリファラライブラリを追加してください。
下記の通り、build.gradleファイルに追加します。

dependencies {
  implementation 'com.google.android.gms:play-services-ads-identifier:{version}'
  implementation 'com.android.installreferrer:installreferrer:{version}'
}

Metaインストールリファラ実装

Metaインストールリファラー を収集できるようにするには、次のクエリをAndroid マニフェストに追加します。

<queries>
  <package android:name="com.facebook.katana" />
</queries>

<queries>
  <package android:name="com.instagram.android" />
</queries>

また、Facebook SDK (Meta)を使用していない場合は、下記をAndroidManifestファイルに追記してください。

<meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/facebook_app_id" />

次に、下記をstrings.xmlファイルに記載してください。YOUR_META_APP_IDはお使いのアプリのMeta App IDになります。

<string name="facebook_app_id" translatable="false">YOUR_META_APP_ID</string>

アプリストア設定

デフォルトでは, unspecifiedがアプリストアの設定になります。アプリに応じて、アプリストアの値をgoogleplayまたはamazonに更新します。

1. AndroidManifest.xml:

<meta-data
    android:name="TENJIN_APP_STORE"
    android:value="googleplay" />

2. setAppStore():

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");

instance.setAppStore(TenjinSDK.AppStoreType.googleplay);

SDK初期化

1. Appsページから SDK_KEY を取得します。注: SDK_KEY はアプリごとに一意です。同じアプリに対して最大3つまでキーを作成できます。

   

2. メインActivityにおいて、import com.tenjin.android.TenjinSDK;を含めてください。
   3a. 各ActivityのonResumeメソッドにおいて、下記コードを追加してください。

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
instance.connect();

注: アプリ内でonCreateとonResumeの間でユーザーの同意を求めるロジックがある場合、同意しないユーザーは onResumeで追跡されないため、TenjinSDKの初期化にはonResumeではなくonCreateを使用してください。

注: アプリの初回起動だけでなく、すべてのonResumeにこのコードを実装するようにしてください。推奨事項に従わない場合は、適切なサポートを提供できないか、アカウントが停止される可能性があります。

その他のAndroidストア

アプリをGooglePlayストアまたはAmazonストア以外(その他のAndroidストア)に配布する場合は、次の初期設定を実装します。

パーミッション

manifestファイルに下記のパーミッションを追加します。

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <!-- Required to get network connectivity (i.e. wifi vs. mobile) -->

2022年4月1日より、ターゲットAPIレベルが32(Android 13)のアプリでGoogle広告IDを取得するには、下記のパーミッションが必要となります。できるだけ早く下記パーミッションの追加をお願いいたします。 下記のパーミッションを使用するには、1.12.8以上のバージョンのAndroid SDKを使用する必要があります。

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

Android広告ID (AAID)とインストールリファラ

Android広告ID(AAID)とインストールリファラライブラリを追加してください。
下記の通り、build.gradleファイルに追加します。

dependencies {
  implementation 'com.google.android.gms:play-services-ads-identifier:{version}'
  implementation 'com.android.installreferrer:installreferrer:{version}'
}

IMEIを使用したアドネットワークを使用する場合は、下記のパーミッションを含めてください。

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

OAID

TenjinはAndroidのOAIDを使用したAndroidアプリストアのトラッキングをサポートしています。OAIDライブラリを実装した場合のオプションは下記の通りです。

MSA OAID

MSA OAIDは、MSA (Mobile Security Alliance)が提供する、中国で製造されるデバイスで取得可能な広告IDです。MSAライブラリを実装する場合は, oaid_sdk_1.0.25.aarとsupplierconfig.jsonをダウンロードします。また、下記をgradleファイルに追加します。

implementation files('libs/oaid_sdk_1.0.25.aar')

必ずsupplierconfig.jsonをプロジェクトのassetsフォルダにコピーしてください。

Huawei OAID

中国以外では、Huaweiによって提供されるOAIDを取得することが可能です。
Huawei OAIDライブラリを追加するには下記の手順を実施します。

build.gradleファイル内で、Huawei SDKに対するMavenのアドレスを追加します。

allprojects {
    repositories {
        google()
        maven { url 'https://developer.huawei.com/repo/' }
    }
}

dependencies {
    implementation 'com.huawei.hms:ads-identifier:{version}'
}

Huaweiインストールリファラ

Huaweiアプリギャラリーにてアプリをプロモーションする場合, 上記のHuawei OAID SDK及び インストールリファラライブラリを追加します。

dependencies {

    implementation 'com.huawei.hms:ads-identifier:{version}'
    implementation 'com.huawei.hms:ads-installreferrer:{version}'

}

アプリストア設定

デフォルトでは, unspecifiedがアプリストアの設定になります。アプリストアの値をotherに更新します。

1. AndroidManifest.xml:

<meta-data
    android:name="TENJIN_APP_STORE"
    android:value="other" />

2. setAppStore():

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");

instance.setAppStore(TenjinSDK.AppStoreType.other);

SDK初期化

1. Appsページから SDK_KEY を取得します。注: SDK_KEY はアプリごとに一意です。同じアプリに対して最大3つまでキーを作成できます。
   

2. メインActivityにおいて、import com.tenjin.android.TenjinSDK;を含めてください。
   3a. 各ActivityのonCreateメソッドにおいて、下記コードを追加してください。

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
instance.connect();

注: アプリの初回起動だけでなく、すべてのonCreateにこのコードを実装するようにしてください。推奨事項に従わない場合は、適切なサポートを提供できないか、アカウントが停止される可能性があります。

難読化設定

-keep class com.tenjin.** { *; }
-keep public class com.google.android.gms.ads.identifier.** { *; }
-keep public class com.google.android.gms.common.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep class * extends java.util.ListResourceBundle {
    protected java.lang.Object[][] getContents();
}
-keepattributes *Annotation*

OAIDのクラスについては難読化しないでください。

-keep class XI.CA.XI.**{*;}
-keep class XI.K0.XI.**{*;}
-keep class XI.XI.K0.**{*;}
-keep class XI.xo.XI.XI.**{*;}
-keep class com.asus.msa.SupplementaryDID.**{*;}
-keep class com.asus.msa.sdid.**{*;}
-keep class com.bun.lib.**{*;}
-keep class com.bun.miitmdid.**{*;}
-keep class com.huawei.hms.ads.identifier.**{*;}
-keep class com.samsung.android.deviceidservice.**{*;}
-keep class com.zui.opendeviceidlibrary.**{*;}
-keep class org.json.**{*;}
-keep public class com.netease.nis.sdkwrapper.Utils {public <methods>;}

Huaweiのライブラリを使用している場合は、下記の設定を行います。

-keep class com.huawei.hms.ads.** { *; }
-keep interface com.huawei.hms.ads.** { *; }

追加実装

GDPR対応

GDPRへの対応において、Tenjin SDKではデバイス/ユーザのオプトイン, オプトアウトおよび各デバイスパラメータのオプトイン, オプトアウトが可能です。OptOut()メソッドにより、Tenjinにリクエストが送られることはありません。

オプトイン/オプトアウトを実装するには:

import com.tenjin.android.TenjinSDK;

public class TenjinDemo extends ActionBarActivity {
    @Override
    public void onResume() {
        //standard code
        super.onResume()

        //Integrate TenjinSDK connect call
        String apiKey = "<SDK_KEY>";
        TenjinSDK instance = TenjinSDK.getInstance(this, apiKey);

        boolean userOptIn = checkOptInValue();

        if (userOptIn) {
            instance.optIn();
        }
        else {
            instance.optOut();
        }

        instance.connect();

        //Your other code...
        //...

    }

    protected boolean checkOptInValue(){
        // check opt-in value
        // return true; // if user opted-in
        return false;
    }
}

• 特定のデバイスパラメータをオプトイン,オプトアウトするにはOptInParams() または OptOutParams()メソッドを使用します。OptInParams()メソッドにより指定されたパラメータのみを送信します。OptOutParams()メソッドにより、指定されたパラーメータ以外のパラメータを送信します。

• 注意点：Tenjin上で正しくユーザをトラッキングするには、advertising_idが必要となります。

  • advertising_id

• IMEIまたはOAIDを使用したネットワークでプロモーションを実施する場合は、下記のパラメータが必須となります。

  • imei
  • oaid

• Google Adsでプロモーションを行う場合は、下記のパラメータが必須となります。

  • platform
  • os_version
  • app_version
  • os_version_release
  • locale
  • device_model
  • build_id

特定のデバイスパラメータのみを取得するには、OptInParams()を使用します。下記具体例では、ip_address, advertising_id, developer_device_id, limit_ad_tracking, referrerのみを取得しています。

String apiKey = "<SDK_KEY>";
TenjinSDK instance = TenjinSDK.getInstance(this, apiKey);

String[] optInParams = {"ip_address", "advertising_id", "limit_ad_tracking", "referrer"};
instance.optInParams(optInParams);

instance.connect();

特定のデバイスパラメータ以外のパラメータを取得するには、OptOutParams()メソッドを使用します。下記具体例では、locale, timezone, and build_id以外のパラメータを送信ししています。

String apiKey = "<SDK_KEY>";
TenjinSDK instance = TenjinSDK.getInstance(this, apiKey);

String[] optOutParams = {"locale", "timezone", "build_id"};
instance.optOutParams(optOutParams);

instance.connect();

CMPを用いたオプトイン/アウト

ユーザーのデバイスにすでに保存されている CMP同意 (目的 1)の情報を使用して、Tenjin SDKを自動的にオプトインまたはオプトアウトできます。このメソッドは、オプトインかオプトアウトかを示すブール値を返します。

optInOutUsingCMP()

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
optInOut = instance.optInOutUsingCMP(); 

デバイスパラメータ

アプリ内課金イベント

ユーザの課金動向を理解するために, transactionイベントをTenjinに送信することが可能です。

重要: 管理画面のAppsタブ -> 該当のAndroidアプリ -> Editより、Public Keyを入力してください。
Publick KeyはBase64でエンコードされたRSA公開キーで、Google Playデベロッパーコンソールの選択したアプリ > Monetize > Monetization setup > Google Play Billing > Licensing: Base64-encoded RSA public key、の箇所から取得できます。

Android の場合、現在サポートされているのはGoogle PlayからのIAPトランザクションのみであることに注意してください。

Public Key入力後, 下記のTenjin SDKメソッドをご利用ください。

public void transaction(String productId, String currencyCode, int quantity, double unitPrice, String purchaseData, String dataSignature)

例:

public void sendPurchaseEvent(Purchase purchase, Double price, String currencyCode) {
    String sku = purchase.getSku();
    String purchaseData = purchase.getOriginalJson();
    String dataSignature = purchase.getSignature();

    TenjinSDK instance = getTenjinInstance();
    instance.transaction(sku, currencyCode, 1, price, purchaseData, dataSignature);
}

コード実装後、課金イベントが正しく検証されているかを確かめるためにテストトランザクションを送ってください。こちらよりお使いのテスト端末のGoogle広告IDを追加後、テスト用トランザクションをお送りください。SDK Live ページより検証後の課金イベントがリアルタイムに確認できます。

免責事項: Tenjinで初めて課金イベントを実装する場合は、課金データを使用してユーザー獲得キャンペーンを拡大する前に、使用している他のツールでデータが正しいことを確認してください。

Amazonアプリストア

Amazonアプリストアのレシート検証には、receiptIdパラメータとuserIdパラメータが必要です。

重要: Amazon アプリの共有キーを Tenjinダッシュボードに追加する必要があります。共有キーは、Amazonアプリストアの開発者アカウントから取得できます。

カスタムイベント

注意点: SDK初期化処理の前にカスタムイベントを送らないようにしてください。

カスタムイベントの送付にはeventWithName(String name)メソッドを使います。

カスタムイベントを利用して、特定のイベントを獲得したユーザの流入元のコスト情報などに紐付けることが可能です。下記が実装例となります。

String apiKey = <SDK_KEY>;
TenjinSDK instance = TenjinSDK.getInstance(this, apiKey);

//Integrate a custom event with a distinct name - ie. swiping right on the screen
instance.eventWithName("swipe_right");

INTEGER型の値をvalueをカスタムイベントに含める方法

カスタムイベントにはINTEGER型のvalueを含めることができます：eventWithNameAndValue(String name, int value)

Tenjinは同じeventNameのイベントのカウントまたは総和を計算するのにeventValueを使用します。データボルトをお使いの場合、これらのvaluesを使って追加のメトリックを計算することができます。

String apiKey = <SDK_KEY>;
TenjinSDK.instance = TenjinSDK.getInstance(this, apiKey);

//Integrate a custom event with a distinct name and value - ie. paying 100 virtual coins for an item
instance.eventWithNameAndValue("item", 100);

上記実装例において、管理画面上でitemというイベント名のイベントのvalueの総和と平均を確認することが可能です。valueはINTEGER型であることにご注意ください。

サーバ間インテグレーション

Tenjinはサーバ間のインテグレーションもサポートしております(有償のプロダクト)。これにより、SDKの実装を必要とせずに、インストールおよびインストール後のイベントをサーバーからTenjinサーバーに直接送信できるようになります。ドキュメントをご覧になりたい方は、support@tenjin.comまでメールをお送りいただき、料金についてご相談ください。

アプリサブバージョン

A/Bテストを実施する場合、appendAppSubversionメソッドを用いて、アプリバージョンに固定の数値を付加することが可能です。例えば、アプリのバージョンが1.0.1でappendAppSubversion: @8888をセットすると、レポートされるアプリバージョンは1.0.1.8888となります。データボルトを用いれば、このアプリバージョンごとのパフォーマンスを分析することが可能です。

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
instance.appendAppSubversion(8888);
instance.connect();

Live Opsキャンペーン

アプリ開発者は、自社サーバーまたはTenjinと連携していないネットワークにカスタムでコールバックを送信できます。これにより、開発者はこれらのユーザーレベルの属性データをリアルタイムで収集して分析できます。以下は、Tenjinのカスタムコールバックを使用した使用例です。

• 内製のデータ分析ツールがある場合、カスタム コールバックを使用すると、デバイス レベルごとに属性データをゲーム内データに関連付けることができます。

• ユーザーのアトリビューションソースに応じて、さまざまなアプリコンテンツを表示します。たとえば、ユーザーAがオーガニックに関連付けられ、ユーザーBが Facebookに関連付けられているとします。ユーザー Bの方がアプリに関心を持っている可能性が高いため、ユーザーがアプリをインストールした後に特別なゲーム内オファーを表示することができます。

より具体的な使用例について相談をご希望の場合は、Tenjinのサクセスマネージャーまでお問い合わせください。

カスタマーユーザー ID

イベントのパラメーターとして送信するカスタマーユーザー IDを設定および取得できます。

.setCustomerUserId(userId: "user_id")

.getCustomerUserId()

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
instance.setCustomerUserId(userId: "user_id");
userId = instance.getCustomerUserId(); 

Analytics Installation ID

下記のメソッドを用いて、ランダムに生成され、デバイスのローカルストレージに保存されているユニークなAnalytics IDを取得できます。
getAnalyticsInstallationId()

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
analyticsId = instance.getAnalyticsInstallationId; 

イベントのキャッシュ/リトライ

リクエストが失敗した場合、またはユーザーがインターネットに接続していない場合のイベントとIAPの再試行とキャッシュを有効/無効にできます。これらのイベントは、新しいイベントがキューに追加され、ユーザーが接続を回復した後に送信されます。

setCacheEventSetting(true)

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
instance.setCacheEventSetting(setting: true);

インプレッションレベル広告収益の実装

Tenjinでは下記のメディエーションプロバイダにおいて、インプレッションレベルの広告収益(ILRD)をサポートしています。

• AppLovin
• Unity LevelPlay
• HyperBid
• AdMob
• TopOn
• CAS
• TradPlus

この機能を使用すると、ユーザーへの広告のインプレッションごとに広告収益に対応するイベントを受け取ることができます。この機能を有効にするには、以下の手順に従ってください。

Google DMAパラメータ

すでに CMPが実装されている場合、Google DMAパラメータはTenjin SDKによって自動的に収集されます。 Tenjin SDKでの追加実装は必要ありません。 CMPをオーバーライドしたい場合、または独自の同意メカニズムを使用したい場合は、以下メソッドを使用できます。

setGoogleDMAParameters(boolean, boolean)

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
instance.setGoogleDMAParameters(adPersonalization, adUserData); 

Google DMAパラメータの収集を明示的に管理するために、いつでも柔軟にオプトインまたはオプトアウトできます。デフォルト設定はオプトインですが、OptInGoogleDMAまたは OptOutGoogleDMAメソッドを使用して設定を簡単に調整でき、データプライバシー設定を完全に制御できます。

instance.optInGoogleDMA(); 
instance.optOutGoogleDMA(); 

テスト

実装が正しくできているかどうかを確認するには、SDK Live Dataで確認できます。管理画面のDIAGNOSE-> Test devicesより、テストデバイスのリストにadvertising_idを追加します。SDK Live Dataにアクセスして、アプリからテストイベントを送信します。イベントがリアルタイムで確認できます。