Android SDK 統合ガイド

 

新しいビデオガイド

統合プロセスの詳細については、このビデオをご覧ください。ビデオと以下のガイドの両方を使用することをお勧めします。

始める前にSDKの前提条件

Singular SDKの統合の手順に従ってください:計画と前提条件

これらのステップはSingular SDKを統合するための前提条件です。

1.プロジェクトへのSDKの追加

1.1 Gradleを使用したSDKの追加

注:Gradle 7以降、Androidは プロジェクトやモジュールレベルの build.gradle 宣言よりもsettings.gradleの集中リポジトリ宣言を 使用することを推奨して います。

  1. SingularのSDKリポジトリを settings.gradleファイルに追加します:

    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
    google()
    mavenCentral()
    maven { url 'https://maven.singular.net/' }
    }
    }

    または古いバージョンのGradleでは、SingularSDKリポジトリをproject/build.gradleファイルに追加します:

    repositories {
            mavenCentral()
    maven { url 'https://maven.singular.net/' } }
  2. app/build.gradleの依存関係リストにSingularライブラリを追加します:

    dependencies {
        implementation 'com.google.android.gms:play-services:6.5.87'
        implementation fileTree(dir: 'libs', include: ['*.jar'])
        ...
        implementation 'com.singular.sdk:singular_sdk:12.5.5'
        ...
    }

    さらに、アプリがSamsung Galaxy Storeを通じて配布される場合、Samsung Galaxy Storeのインストールリファラーをサポートするために以下を追加します:

    dependencies {
          ...
          implementation 'store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0'
          ...
        }
  3. Singular SDKのtransitive dependenciesを無効にしている場合は、app/build.gradleに以下を追加します:

    dependencies {
    ... implementation 'com.android.installreferrer:installreferrer:2.2' implementation 'com.google.android.gms:play-services-appset:16.0.0' ... }
  4. アプリがGoogle Play Services API 17.0.0 以降を実装していない場合は、app/build.gradleファイルに以下の依存関係を追加します:

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

Note:Gradle 1.x-2.x ユーザーは、"implementation" の代わりに "compile" を使用して依存関係を追加してください。

1.2.Gradleを使用しないSDKの追加

手動でSDKをダウンロードする
  1. ページ上部のリンクからSDKをダウンロードします。
  2. SDKパッケージを解凍し、Singular.aarをAndroidプロジェクトのlibsディレクトリのlibsフォルダに追加します。存在しない場合は、プロジェクトフォルダ(通常は<project>/app/libs)にlibsというディレクトリを作成します。
Mavenを使用してSDKを追加する

プロジェクトのpom.xmlにmavenリポジトリを追加します:

<project ...>
<repositories>
    <repository>
      <id>singular.net</id>
      <url>http://maven.singular.net/</url>
    </repository>
 </repositories>
</project>

依存関係を追加します:

<dependency>
    <groupId>com.singular.sdk</groupId>
    <artifactId>singular_sdk</artifactId>
    <version>12.0.2</version>
</dependency>
Eclipseを使用したSDKの追加

EclipseのAARプラグインを使うことができます: gradle-eclipse-aar-plugin

プラグインを使いたくない場合は、以下の手順に従ってください:

  1. singular_sdk-12.5.5.aarを解凍します。
  2. classes.jarをsingular_sdk-12.5.5.jarにリネームします(これがメインのSDK jarです)。
  3. com.android.installreferrer:installreferrer:2.2」ライブラリを、お好みの方法でプロジェクトに追加します。
  4. AARに含まれるAndroidManifest.xmlからBIND_GET_INSTALL_REFERRER_SERVICEパーミッションをAndroidManifest.xmlにコピーします。
  5. AARに含まれるAndroidManifest.xmlからCHECK_LICENSEパーミッションをAndroidManifest.xmlにコピーします。
Proguardを使用したSDKの追加

proguard.configファイルに以下のコードを追加します:

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
# Google課金ライブラリを使用して'revenue'関数を呼び出している場合は、この行のコメントを外します。
#-keep public class com.android.billingclient.** { *; }

1.3.必要なパーミッションの追加

AndroidManifest.xmlファイルの<manifest>タグの下に、これらのパーミッションを追加します:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />

注:アプリのビルドがAndroid 12/APIレベル31以上をターゲットにしている場合は、Google Advertising IDにアクセスするためのパーミッションを追加してください:

<uses-permission android:name="com.google.android.gms.permission.AD_ID" />
Kids SDKを統合する場合は、このパーミッションを追加しないでください。

さらに、アプリがSamsung Galaxy Storeを通じて配布され、Android 11以上をターゲットにしている場合は、Samsung Galaxy Storeのインストール・リファラーをサポートするために以下を追加してください:

<queries>
  <package android:name="com.sec.android.app.samsungapps" />
  </queries>
注意してください:アプリにandroid.permission.GET_TASKSパーミッションがある場合、ユーザーが実際にアプリを開く前にアプリが初期化される可能性があります。これはSingular SDKを初期化し、インストール時間の不一致を引き起こす可能性があります。この問題を防ぐには、パーミッションが不要であれば削除するか、Singular SDKの初期化呼び出しをコード内の別の場所に移動し、ユーザーが初めてアプリを開いた後にのみ呼び出されるようにします。

2.基本的なSDK統合のセットアップ

注意:Singular SDKを実装する際には、GDPR、CCPA、COPPAなど、ビジネスを展開している地域で制定されている様々なプライバシー法に準拠することを忘れないでください。詳しくはSDKのオプトインとオプトアウトをご覧ください。

2.1.Singularライブラリのインポート

Singularライブラリをインポートするには、以下のインポートをMainActivityファイルに追加します:

Java (MainActivity.java) Kotlin (MainActivity.kt)
import com.singular.sdk.*;

2.2.構成オブジェクトの構築

SDKを初期化する前に、SingularConfigオブジェクトを作成する必要があります。このオブジェクトには以下が含まれます:

  1. SDKキーとSDKシークレット(これらを取得するには、Singularアカウントにログインし、DEVELOPER TOOLS > SDK Integration > SDK Keysにアクセスしてください。
  2. 任意で設定したいSDK設定。
  3. METAインストール・リファラー帰属のサポート

    Meta Install Referrer」アトリビューションを有効にするために必要なSDK設定です:

    1. Singular構成オブジェクトにFacebookアプリIDを入力してください。
      // META インストールリファラーを有効にするには
      config.withFacebookAppId("ここに Facebook アプリ ID を入力してください");
    アプリのFacebookアプリIDはどこで確認できますか?

以下のコード例では、Singular SDKを初期化する前に設定オブジェクトを作成し、共通の設定オプションを設定しています。

次のセクションでは、これらのオプションの詳細とカスタマイズ方法について説明します。

Java (MainActivity.java) Kotlin (MainActivity.kt)
@Override
protected void onCreate(Bundle savedInstanceState) {
    ...
// コンフィギュレーション・オブジェクトの作成 SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");

// ディープリンク・ハンドラーを設定する config.withSingularLink( getIntent(), new SingularLinkHandler() { @Override public void onResolved(SingularLinkParams params) { String deeplink = params.getDeeplink(); String passthrough = params.getPassthrough(); boolean isDeferred = params.isDeferred(); // ここにディープリンク処理コードを追加する } } );

Singular.init(context, config); ... }

 

SingularConfigメソッドリファレンス:利用可能なすべての".with "オプションを見る

下の表はSingularConfigオブジェクトで利用可能な全ての".with "メソッドの一覧です。

各機能の詳細については、以下のセクションまたはAdvanced Optionsを参照してください。

メソッド

説明

.withFacebookAppId(String facebookAppID)

FacebookアプリIDを設定します。Meta Install Referrer」アトリビューションに必要です。

"Where can I find an app's Facebook App ID?" を参照してください。

.withCustomUserId(String customId)

ユーザーIDをSingularに送信します。

.withSingularLink(getIntent(), SingularLinkHandler handler)

Singular Linksでディープリンクを有効にする。

.withDDLTimeoutInSec(long timeout)

アプリが最初に開かれたときに、Singularが遅延されたディープリンクを検索する時間の長さを設定する。

.withDDLHandler (DeferredDeepLinkHandler handler)

(新しいSingular Linksの代わりに)レガシートラッキングリンクでディープリンクを有効にします。

.withOpenURI (URI openURI)

インテントからURIを取得します(Singularから発信されていないリンクでアプリが開かれた場合にディープリンクを処理するため)。

.withGlobalProperty(String key, String value, boolean overrideExisting)

グローバルプロパティを指定された値に設定します。キーと値は、アプリから送信されるイベント/セッションと一緒にSingularに送信されます。

.withSessionTimeoutInSec (long timeout)

セッションタイムアウトを設定します。

.withFCMDeviceToken(String token)

最初のセッションで送信するFCMトークンを設定します。

.withLoggingEnabled()

ロギングを有効にします。

.withLogLevel (int level)

ロギングレベルを設定します(デフォルトはLog.ERROR)。

2.3.ディープ・リンク・サポートの追加

ディープリンクは、アプリ内の特定のコンテンツにつながるリンクです。アプリがインストールされたデバイスでユーザーがディープリンクをクリックすると、アプリが開き、特定の製品や体験が表示されます。 シンギュラートラッキングリンクは、ディープリンクだけでなく、ディファードディープリンクも含むことができます(詳しくは、 ディープリンクFAQと シンギュラートラッキングリンクFAQをご覧ください)。

シンギュラーリンクを使用してディープリンクを有効にする

アプリでディープリンクを有効にするには、シンギュラーリンクの前提条件を参照してください。

ディープリンクインテントフィルタの追加

アクティビティでディープリンクのサポートを有効にするには、AndroidManifest.xmlに次のようなインテント・フィルタを追加します。ディープリンクで開くべきアクティビティが複数ある場合は、アクティビティごとにこれを行います。

注意: インテントには「android:host」値を設定しないでください。もし'android:host'値を使用しなければならない場合、必ずAppスキームのSingular Appsページ設定にホスト値を含め、すべてのSingularディープリンクに同じ'scheme://host'値を使用してください。

<activity> 
    <intent-filter>
        <data android:scheme="singular-example" />
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
    </intent-filter>
</activity>

ディープリンクの処理

Singular SDKは、アプリを開くきっかけとなったトラッキングリンクの詳細を読み取るハンドラメカニズムを提供します。ハンドラのサンプルは、上記の「 構成オブジェクトの構築」のサンプルコードに含まれています。

注釈SingularLinkHandler が呼び出されるのは、アプリが Singular リンクを介して開かれた場合のみです ( Singular Links FAQ を参照してください)。 その他のタイプのアプリリンクは、Singular Config オブジェクトの作成時にsupportedDomainsにドメインが含まれている場合にのみトリガされます。 詳細は、"Singular 以外のディープリンクの処理" を参照してください。

ディファード・ディープ・リンクのタイムアウトの変更

デフォルトでは、アプリが特定のデバイスからSingularに最初のセッションを送信すると、Singularサーバはそのデバイスに一致する遅延されたディープリンクがあるかどうかをレコードで調べます(「遅延されたディープリンクとは」を参照)。 遅延されたディープリンクが見つかると、それを処理するためにアプリに送り返されます。しかし、60秒以内に延期されたディープリンクが見つからない場合、サーバーは検索を停止します。

SingularConfigオブジェクトの作成時にwithDDLTimeoutInSecを呼び出すことで、タイムアウト値を変更できます。 以下の例では、タイムアウトを30秒に変更しています:

SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");
...
config.withDDLTimeoutInSec(30);
...
Singular.init(context, config);

非 Singular ディープリンクの処理

Singular SDKはSingular以外のディープリンクをサポートしています。これは、Google Adsなどのパートナーのアトリビューションを測定するために必要です。

Android SDKバージョン12.1.1から、Singular以外のユニバーサルリンクがデフォルトでサポートされています。新しいバージョンのSDKを使用している場合、サードパーティーリンクをサポートするためのアクションは必要ありません。

2.4.Singularの初期化

Singular SDKはアプリを開くたびに初期化する必要があります。 これはSingularのすべてのアトリビューション機能の前提条件であり、また新しいユーザーセッションをSingularに送信します(セッションはユーザーのリテンションを計算するために使用されます)。

Singularを初期化するには、以下のコードを使います:

Singular.init(context, config);
パラメータ 説明
Context context アプリケーションクラスから、コンテキストとしてthisまたはgetApplicationContext()を渡すことができます。アクティビティ内からアプリケーションコンテキストを取得するには、currentActivity.getApplicationContext()を呼び出します。
SingularConfig config 前のステップで作成したSingularConfigオブジェクト。

initメソッドは、アプリ内のあらゆる場所で呼び出すことができますが、イベントが報告される前に呼び出される必要があります。initは、メインアクティビティのonCreateや、ディープリンクで直接開かれるアクティビティで呼び出すことをお勧めします

注意: ディープリンクで開かれるアクティビティ内では、Singularを初期化する必要があります(ディープリンクの実装を参照)。したがって、アプリケーションのonCreateでSingularを初期化することはお勧めしません。Singularがアプリケーションレベルで初期化され、アクティビティ内で再び初期化されると、Singularデータベース内でセッションが重複してしまいます。

2.5.ユーザーIDをSingularに送信する(オプション)

Singular SDKのメソッドを使用して、内部ユーザーIDをSingularに送信することができます。

注意: Singularのクロスデバイスソリューションをご利用の場合は、すべてのプラットフォームでユーザーIDを収集する必要があります。

  • ユーザーIDはどのような識別子でもかまいませんが、PII(個人を特定できる情報)を公開するべきではありません。 例えば、ユーザーのメールアドレス、ユーザー名、電話番号は使用しないでください。Singularは、お客様のファーストパーティデータにのみユニークなハッシュ値を使用することを推奨します。
  • Singularに渡すユーザーIDは、すべてのプラットフォーム(ウェブ/モバイル/PC/コンソール/オフライン)で同じ内部ユーザーIDを使用する必要があります。
  • Singularはユーザーレベルのエクスポート、ETL、内部BIポストバック(設定されている場合)にユーザーIDを含めます。ユーザーIDはファーストパーティデータであり、Singularが他者と共有することはありません。
  • ユーザーIDの値は、Singular SDKメソッドで設定されると、unsetCustomUserId メソッドで設定が解除されるまで、またはアプリがアンインストールされるまで保持されます。アプリを終了または再起動しても、ユーザーIDはアンセットされません。

ユーザーIDを設定するには、setCustomUserId メソッドを使用します。設定を解除するには(ユーザがアカウントから「ログアウト」した場合など)、unsetCustomUserId を呼び出してください。

注:複数のユーザが1つのデバイスを使用する場合、ログインとログアウトのたびにユーザIDを設定および解除するログアウトフローを実装することを推奨します。

アプリを開いたときにユーザーIDがすでに分かっている場合は、Singular SDKを初期化する前にsetCustomUserId 。こうすることで、Singularは最初のセッションからユーザーIDを持つことができます。しかし、ユーザーIDは通常、ユーザーが登録するかログインを実行するまで使用できません。その場合は、登録フローが完了した後にsetCustomUserId

Singular.setCustomUserIDメソッド
説明 ユーザーIDをSingularに送信します。
シグネチャ public void setCustomUserId(string customUserId)
使用例
Singular.setCustomUserId("custom_user_id");
Singular.unsetCustomUserIDメソッド
説明 Singularに送信されたユーザーIDの設定を解除します。
シグネチャ public void unsetCustomUserId()
使用例
Singular.unsetCustomUserId();
オプション:カスタムユーザーID デバイスマッピング

重要:この高度なエンタープライズ機能は、例外的な場合にのみ使用できます。実装する前にSingularのソリューションエンジニアにご相談ください。

Singularはサーバー間の統合により、追加のモバイルイベント追跡データを受け取ることができます。この機能を利用するには、ユーザーIDをSingularのモバイルデバイス追跡識別子にマッピングする必要があります。

注意:Singular SDKを初期化した後、またはユーザーIDを取得した後、できるだけ早くこのメソッドを呼び出してください。

Singular.setDeviceCustomUserId メソッド
説明 ログイン時と同じカスタムユーザーIDを設定し、Singularのトラッキング識別子にマッピングします。
シグネチャ public void setDeviceCustomUserId(string customUserId)
使用例
Singular.setDeviceCustomUserId("custom_user_id");

2.6.グローバルプロパティの実装 (オプション)

Singular SDKでは、アプリから送信されるセッションやイベントごとにSingularサーバーに送信するカスタムプロパティを定義できます。これらのプロパティは、ユーザー、アプリのモードやステータスなど、あらゆる情報を表すことができます。これらのプロパティを設定すると、レポートのディメンションとして利用できるようになり、データを分解するために使用できます。

例えば、ゲームアプリがある場合、"Level "というプロパティを定義し、初期値として "0 "を設定することができます。アプリから送信されるすべてのセッションとイベントは、"Level":"0".ユーザがレベルアップしたら、プロパティを "1 "にリセットします。すると、セッション数、イベント数、収益データなどのレポートをユーザーレベル別に取得することができます。

  • グローバル・プロパティは5つまで定義できます。
  • これらのプロパティは、あなたが設定を解除するか、ユーザーがアプリをアンインストールするまで、アプリの実行間で(あなたが与えた最新の値で)持続します。
  • 各プロパティ名と値の長さは200文字までです。これより長いプロパティ名や値を渡すと、200文字に切り詰められます。
  • グローバル・プロパティにはアクセス可能で、ユーザレベルのエクスポートと ポストバックで使用できます。将来的には、集計レポートのサポートが追加される予定です。ご質問がある場合、またはグローバルプロパティサポートのアップデートに興味がある場合は、Singularカスタマーサクセスマネージャーにお知らせください!

SingularConfig によるグローバルプロパティの設定

SDKを初期化する前に、withGlobalPropertyメソッドを使用してSingularConfigを通してグローバルプロパティを設定することができます。

グローバルプロパティとその値はアプリの実行間で持続するため、設定しようとしているプロパティがすでに別の値に設定されている可能性があることに注意してください。既存のプロパティを新しい値で上書きするかどうかをSDKに指示するには、overrideExistingパラメータを使用します。

withGlobalProperty メソッド
説明 グローバル プロパティを設定します。
シグネチャ withGlobalProperty(String key, String value, boolean overrideExisting)
使用例
// 2つのグローバル・プロパティを設定し、既存の値を上書きする。
SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")
  .withGlobalProperty(“MyProperty”, “MyValue”, true)
  .withGlobalProperty(“AnotherProperty”, “AnotherValue”, true);

初期化後のグローバル・プロパティの設定

以下のメソッドを使用して、アプリの実行中にいつでもグローバル・プロパティを設定、解除、取得できます。

Singular.setGlobalProperty メソッド
説明

グローバル・プロパティを指定された値に設定します。

注意事項

  • プロパティがまだ存在せず、他のグローバル・プロパティがすでに5つ存在する場合、プロパティは追加されません。
  • プロパティが既に設定されている場合、overrideExisting パラメータは、既存の値がオーバーライドされるかどうかを決定します。
  • このメソッドは、プロパティが正常に設定された場合はtrue を返し、そうでない場合はfalse を返します。
シグニチャ public static bool setGlobalProperty(String key, String value, boolean overrideExisting)
使用例
boolean result = Singular.setGlobalProperty(“MyProperty”, “MyValue”, true);
Singular.getGlobalPropertiesメソッド
説明 すべてのグローバル・プロパティとその現在の値を Map として取得します。
シグネチャ public static Map<String, String> getGlobalProperties()
使用例
Map<String, String> map = Singular.getGlobalProperties();
Singular.unsetGlobalPropertyメソッド
説明 グローバルプロパティを削除する。
シグネチャ public static void unsetGlobalProperty(String key)
使用例
Singular.unsetGlobalProperty(“MyProperty”);
Singular.clearGlobalPropertiesメソッド
説明 すべてのグローバル・プロパティを削除します。
シグネチャ public static void clearGlobalProperties()
使用例
Singular.clearGlobalProperties();

3.イベントと収益の追跡

3.1. イベントのトラッキング(非収入)

Singularはアプリ内イベントに関するデータを収集し、キャンペーンのパフォーマンス分析やKPIの測定に役立てることができます。例えば、ゲームアプリでユーザーのログイン、登録、チュートリアルの完了、レベルアップなどのデータを収集したい場合があります。

標準イベントと属性とは何ですか?

Singularは様々な標準イベントをサポートしています。これらの一般的に使用されるイベントは、レポートや最適化のために広告ネットワークでよくサポートされています。もう一つの利点は、標準イベント名を使用すると、Singularが自動的に認識し、手動で定義しなくてもイベントリストに追加されることです。可能な限り標準イベントを使用することをお勧めします。

Singularに送信されるイベントのリスト(付随する属性付き)は、組織のマーケティングKPIに基づいてUA/マーケティング/ビジネスチームが作成する必要があります。ビジネスチームは、How to Track In-App Eventsのガイドに従ってください:Guide For Singular Attribution Customers.

追跡するイベントごとに、さまざまな属性を渡すことができます。イベントごとの推奨標準属性を参照してください。

イベントの送信

コード内で、eventJSONまたはeventメソッドを使用してSingularにイベントを送信します(読みやすさのためにeventJSONを推奨します)

Singular.eventJSON メソッド
説明 ユーザーイベントをJSONObject形式で追加情報と共にSingularに報告します。
シグネチャ

Singular.eventJSON(String name, JSONObject args)

注: 'args' は、1つ以上のキーと値のペアを含むJSONObjectです。キーは文字列で、値はJSONObjectの値として許可されている型であれば何でもよい。
使用例
Java (MainActivity.java) Kotlin (MainActivity.kt)
// 例 1: 標準イベント sng_tutorial_complete を推奨標準属性で送信する。
JSONObject att = new JSONObject();
att.put(Attributes.sngAttrContent.toString(), <TUTORIAL NAME>);
att.put(Attributes.sngAttrContentId.toString(), <CONTENT ID>);
att.put(Attributes.sngAttrContentType.toString(), <TYPE OF CONTENT>);
att.put(Attributes.sngAttrSuccess.toString(), <LOGIN SUCCESS VALUE>);
Singular.eventJSON(Events.sngTutorialComplete.toString(), att);
// 例2:"bonus_points_earned "というカスタムイベントをカスタム属性で送信する。 JSONObject att = new JSONObject();
att.put("Points", 500); Singular.eventJSON("Bonus Points Earned", att);
Singular.eventメソッド
説明 追加情報の有無にかかわらず、ユーザーイベントをSingularに報告します。
シグネチャ

Singular.event(String eventName)
Singular.event(String eventName, Object... args)

注意: 'args' は1つ以上のキーと値のペアです(下記の例を参照)。キーは文字列で、値はJSONObjectの値として許可されている任意の型(すなわち、JSONObject、JSONArray、String、Boolean、Integer、Long、Double、NULL)です。

args' リストには偶数個の要素を含める必要があります。

使用例
Java (MainActivity.java) Kotlin (MainActivity.kt)
// 例 1: 標準イベント sng_tutorial_complete を推奨標準属性で送信する。
Singular.event(Events.sngTutorialComplete.toString(),
  Attributes.sngAttrContent.toString(), <TUTORIAL NAME>,
  Attributes.sngAttrContentId.toString(), <CONTENT ID>,
  Attributes.sngAttrContentType.toString(), <TYPE OF CONTENT>,
  Attributes.sngAttrSuccess.toString(), <SUCCESS>
);

// 例 2: 標準イベント "Subscribe" (sng_subscribe) を送信します。
Singular.event(Events.sngSubscribe.toString());

// 例3:"bonus_points_earned "というカスタムイベントをカスタム属性で送信する。 Singular.event("Bonus Points Earned", "Points", 500);

注意事項

  • サードパーティのパートナーや分析ソリューションを使用する場合は、互換性を保証するためにイベント名と属性を英語で渡すことを強く推奨します。
  • イベント名は32 ASCII文字に制限されています。非ASCII文字の文字列は、UTF-8に変換された後、32バイト以下にする必要があります。
  • 属性と値は500 ASCII文字に制限されます。

3.2.収益のトラッキング

Singularはアプリを通じて得た収益に関するデータを収集し、キャンペーンのパフォーマンスとROIの分析に役立てることができます。Singularはレポート、ログエクスポート、ポストバックでデータを利用できるようにします。

購入オブジェクトを使った収益のトラッキング

収益イベントをSingularに報告する際は、課金ライブラリから受け取った購入オブジェクトを渡すことをお勧めします。これには2つの利点があります:

  1. Singularがトランザクションの詳細をすべて取得するので、Singularのレポートが充実します。
  2. SingularはGoogleからトランザクションのレシートを受け取るので、アプリ内詐欺対策としてトランザクションの検証に使用できます。

リマインダー

  • 2023年8月2日以降、すべての新しいアプリはBilling Libraryバージョン5以降を使用する必要があります。2023年11月1日までに、既存アプリのすべてのアップデートは、Billing Libraryバージョン5以降を使用する必要があります。詳細はこちら。
  • Android 14以上をターゲットとするアプリの場合、PBL 5.2.1またはPBL 6.0.1以上にアップデートする必要があります。

イベントを報告するには、revenueメソッドとcustomRevenueメソッドを使用します。CustomRevenueではカスタムイベント名を渡すことができ、Singularのレポートで収益を収益イベントの種類ごとに分けて表示することができます。

注意:異なる通貨で報告された収益は、Singularアカウントで設定された組織の優先通貨に自動変換されます。

Singular.revenueメソッド
説明 オプションの追加情報を含む収益イベントをSingularに送信します。
シグネチャ

Singular.revenue(String currency, double amount, Object purchase)

注意

  • オブジェクトを渡す場合、Purchase型でなければなりません。
  • 通貨は "USD"、"EUR"、"INR "のような3文字のISO 4217通貨コードで渡します。
使用例
// Google Billing Libraryから受け取った購入オブジェクトを含む収益イベントをSingularに送信します。
Singular.revenue("USD", 5.50, purchase);
Singular.customRevenue メソッド
説明 イベント名とオプションの追加情報を持つ収益イベントを Singular に送信します。
シグネチャ

Singular.customRevenue(String eventName, String currency, double amount, Object purchase)

注意

  • オブジェクトを渡す場合、Purchase型でなければなりません。
  • 通貨は "USD"、"EUR"、"INR "のような3文字のISO 4217通貨コードで渡します。
使用例
// Singularに収益イベントを送信し、イベント名と購入オブジェクトを渡します。
Singular.customRevenue("MyCustomRevenue", "USD", 
5.50, purchase);

Purchaseオブジェクトを使用しない収益の報告

上記の方法で収益イベントを報告することを強くお勧めしますが、購入オブジェクトを渡さずに収益と customRevenueを使用することもできます。代わりに、トランザクションの通貨と金額、およびオプションの商品詳細を渡します。

この方法で収益イベントを報告する場合、Singularは購入レシートを取得せず、トランザクションを検証できないことに注意してください。

続きを読む...
Singular.revenue メソッド (購入オブジェクトなし)

説明

オプションの追加情報を含む収益イベントをSingularに送信します。

シグネチャ

Singular.revenue(String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice)

Singular.revenue(String通貨, double金額)

注意:通貨は、"USD"、"EUR"、"INR" のような3文字のISO 4217通貨コードで渡します。

使用例

// 製品の詳細を含む収益イベントをSingularに送信する
Singular.revenue("EUR", 5.00, "SKU1928375", 
"Reservation Fee", "Fee" , 1, 5.00); // 商品詳細のない収益イベントをSingularに送信する Singular.revenue("USD", 5.50);
Singular.customRevenueメソッド(購入オブジェクトなし)
説明 イベント名とオプションの追加情報を持つ収益イベントをSingularに送信します。
シグネチャ

Singular.customRevenue(String eventName, String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice)
Singular.customRevenue(String currency, double amount)

注意:通貨は、"USD"、"EUR"、"INR "のような3文字のISO 4217通貨コードで渡します。

使用例
// イベント名と商品詳細を記載した収益イベントをSingularに送信します。
Singular.customRevenue("MyCustomRevenue", "EUR", 5.00, 
"SKU1928375", "Reservation Fee", "Fee" , 1, 5.00); // 収益イベントをイベント名とともにSingularに送信する。 Singular.customRevenue("MyCustomRevenue", "USD", 5.50);

3.3.ハイブリッドイベントトラッキング(上級者向け)

Singularでは、アプリに統合されたSingular SDKを通してすべてのイベントと収益を送信することを推奨しています。ただし、Singularは他のソースからイベントと収益を収集することもできます。

Singular SDKから送信されないイベントは、Singularのサーバー間イベントドキュメンテーション要件に準拠し、イベントの属性を正しく設定するために一致するデバイス識別子を提供する必要があります。

重要です

Server-to-Server イベントリクエストで使用されるデバイス識別子がSingularで一致しない場合、不一致が発生します。以下の可能性に注意してください:

  • イベントリクエストがSingular SDKがアプリセッションからデバイス識別子を記録する「前」に受信された場合、そのイベントリクエストは未知のデバイスの「最初のセッション」とみなされ、Singularはそのデバイスをオーガニックアトリビューションとしてアトリビュートします。
  • もしSingular SDKがデバイス識別子を記録していたとしても、Singular SDKの識別子がServer-to-Server Eventリクエストで指定されたデバイス識別子と異なる場合、イベントの帰属は正しくありません。

ハイブリッドイベント追跡ガイド

内部サーバーからのイベント送信

Singularはお客様のサーバーから収益に関するデータを収集し、キャンペーンのパフォーマンスやROIの分析に役立てることができます。

要件

  • アプリ内登録またはログインイベントから、デバイス識別子を取得して渡し、このデータをユーザーIDと共にサーバーに保存します。デバイス識別子はユーザーによって変更される可能性があるため、ユーザーがアプリセッションを生成する際には必ず識別子を更新してください。これにより、サーバー側イベントが正しいデバイスに帰属することが保証されます。
  • サーバー側イベントはプラットフォーム固有であるため、デバイスプラットフォームに一致するデバイス識別子(iOSデバイスのIDFAまたはIDFVなど)のみを使用して送信する必要があります。
  • Singular 内部 BI ポストバック メカニズムを使用して、内部エンドポイントにリアルタイムでイベントをプッシュすると、サーバー側でデータセットを更新できます。内部BI ポストバック FAQ を参照してください。
  • 詳細については、『サーバー間統合』ガイドの「収益の追跡」セクションを参照してください。
収益プロバイダからのイベントの送信
RevenueCatや adaptyのようなサードパーティプロバイダーは、Singularに購入収益や購読収益を提供することができます。

これらのパートナーを有効にする方法の詳細については、以下のリンクを参照してください。

セグメントからのイベント送信

SingularSDKと並行してSegmentからSingularにイベントを送信するには、Segmentに"Cloud-Mode "Destinationを追加する必要があります。こちらのガイドに従ってください。

4.高度なオプション

4.1.短いリファラーリンクの作成

注:この機能はSDKバージョン12.1.1+で利用可能です。 一度作成されたショートリンクは30日間有効です。

ショートリンクを使用すると、長くてパラメータがいっぱいのシンギュラーリンクを、共有に便利な短くて安全なリンクに変換できます。

通常、ショートリンクを動的に作成して、アプリのユーザーが友達と共有してアプリの使用を招待できるようにします。

ショートリンクを作成するには

  • アプリのダウンロードにつながるシンギュラーリンクシンギュラーリンクのFAQを参照)。
  • リンクに動的に追加したいパラメータ(オプションの一覧はトラッキングリンクパラメータをご覧ください)。
  • アプリの新規インストールを、リンクを共有したユーザーまで追跡したい場合は、参照ユーザーの名前とID

以下の例のように、createReferrerShortLinkメソッドを使用してショートリンクを作成します。

Java (MainActivity.java) Kotlin (MainActivity.kt)
// シンギュラーリンクにパラメータを追加するJSONオブジェクトを作成する(リンクURLにパラメータがまだ存在しない場合)。
JSONObject params = new JSONObject();       
try {
      params.put("channel","sms");
      params.put("another parameter","parameter value");
} catch (JSONException e) {
      e.printStackTrace();
}

Singular.createReferrerShortLink (
  "https://sample.sng.link/D52wc/cuvk?pcn=test", // オリジナルのシンギュラーリンクURL
  "Referrer Name",
  "Referrer ID",
  params,
  new ShortLinkHandler() { 
    @Override
      public void onSuccess(final String shortLinkURL) {
        view.post(new Runnable() {
          @Override
          public void run() {
            // シェアロジックをここに追加
          }   
        });
      }

@Override public void onError(final String error) { view.post(new Runnable() { @Override public void run() { // エラーの原因に基づき、関数に渡されたパラメータを再試行/中止/修正するロジック。 } }); } });

4.2.広告収入アトリビューション・サポートの追加

注:バージョン11.0.0から、Singular SDKを通じて広告収入をアトリビューション設定するオプションが追加されました。 旧来の方法(APIコールを使用)で広告収益アトリビューションを設定するオプションも残っており、アプリでSingular SDKをアップデートする必要はありません。

Singular SDKに広告収入アトリビューションのサポートを追加するには:

  1. Singular SDKを最新バージョンにアップデートします。
  2. 広告収益データに使用しているメディエーションプラットフォームに応じて、適切なコードスニペットをSingular SDKインテグレーションに追加します。

注:通貨を3文字のISO 4217通貨コード(例:「USD」、「EUR」、「INR」)で渡します。

アドモブ
  1. 注意: この機能はAdmobアカウントで有効にする必要があります。

    をご覧ください。 https://support.google.com/admob/answer/11322405#getstarted

KotlinJava
var mRewardedAd: RewardedAd? = null

override fun onAdLoaded(rewardedAd: RewardedAd) {
   mRewardedAd = rewardedAd
   mRewardedAd?.setOnPaidEventListener(object : OnPaidEventListener {
      override fun onPaidEvent(adValue: AdValue) {
         val impressionData: AdValue = adValue
         val data = SingularAdData(
            "AdMob",
            impressionData.currencyCode,
            impressionData.valueMicros / 1000000.0)
         Singular.adRevenue(data)
      }
  })
}
AppLovinMax
  1. AppLovin MAXのイベントonMessageReceivedから受け取ったオブジェクトを取得する。
KotlinJava
val message: AppLovinCommunicatorMessage? = null 
val adData: Bundle? = message?.messageData

adData?.let { bundle -
    val data = SingularAdData(
        "AppLovin",
        "USD",
        bundle.getDouble("revenue", 0.0)
    )
    Singular.adRevenue(data)
}
アイアンソース
  1. IronSourceのイベント、OnImpressionSuccessから受け取ったオブジェクトを取得する
  2. IronSourceのARM SDK Postbacksフラグがオンになっていることを確認します。
  3. を参照。https://developers.is.com/ironsource-mobile/general/ad-revenue-measurement-postbacks/#step-1
KotlinJava
val impressionData: ImpressionData? = null

impressionData?.let { data -
    val singularAdData = SingularAdData(
        "IronSource",
        "USD",
        data.revenue)
    Singular.adRevenue(singularAdData)
}
トラッドプラス
  1. impressionDelegateを設定する
  2. TradPlusAdImpressionコールバックにSingularを追加する
KotlinJava
TradPlusSdk.setGlobalImpressionListener(
object : GlobalImpressionManager.GlobalImpressionListener { override fun onImpressionSuccess(tpAdInfo: TPAdInfo?) { if (tpAdInfo == null) return val revenue = tpAdInfo.ecpm.toDouble() / 1000 val data = SingularAdData(
"TradPlus",
"USD",
revenue) Singular.adRevenue(data) } })
その他(ジェネリック)
  1. SingularAdDataオブジェクトを関連データで初期化する
  2. データをSingularに報告
KotlinJava
val data = SingularAdData(
"あなたの広告プラットフォーム",
"通貨コード",
9.90)
Singular.adRevenue(data)

4.3.アンインストール追跡

Android アプリのアンインストールトラッキングを有効にするには、まず、 アンインストールトラッキングの設定に詳細が記載されているように、Singular プラットフォームでアプリを設定します。 その後、以下の手順に従ってください。

注:Google は 2018 年 4 月に GCM API を廃止しました。以下に説明するように、アンインストールトラッキングには Firebase Cloud Messaging (FCM) を使用してください。

I.FCMと統合する:

アンインストールをトラッキングするには、Firebase Cloud Messaging (FCM) プラットフォームのサービスを利用できます。FCM をまだ使用していない場合は、 Android で Firebase Cloud Messaging クライアントアプリをセットアップする方法について、Google の指示に従ってください。

FCMの要件 ( ソース )

FCMクライアントは、Google PlayストアアプリがインストールされたAndroid 4.1以上が動作するデバイス、またはGoogle APIがインストールされたAndroid 4.1が動作するエミュレータが必要です。なお、AndroidアプリのデプロイはGoogle Playストアに限定されません。

サポートされているバージョンのAndroidで動作していないユーザー/デバイスは、Singularアンインストールトラッキングの対象外となります。

II.AndroidManifest.xml ファイルを更新する:

AndroidManifest.xml ファイルを更新して、アプリに必要なインテント フィルタを追加します(MyFirebaseMessagingService を Firebase Service を実装するクラスで置き換えてください):

<service android:name=".java.MyFirebaseMessagingService"
android:exported="false">
    <intent-filter>
        action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

III.FCMデバイストークンの登録と送信

最後に、OnCreate()でSingularConfigを初期化した後、次のようにFCMデバイストークンを設定します:

Singular.setFCMDeviceToken(String fcmDeviceToken);

4.4.古いデバイスでインストールリファラーを収集する

注意: Googleはinstall_referrerインテント・ブロードキャストを廃止予定です。以下を参照ください:まだ InstallBroadcast を使用していますか?2020年3月1日までに Play Referrer APIに切り替えてください。

インストールリファラーは、アトリビューションを決定するための Singular の最も正確なツールであり、Singular の不正行為の検出と分析にも役立ちます。これはGoogle Playストアが提供する識別子で、ユーザーがアプリをインストールする前にクリックした広告を指します。

最新バージョンのGoogle Playストアがあるデバイスでは、Singular SDKはインストールリファラーの値を自動的に収集します(Singularは最新のGoogle Play Referrer APIと統合されているため)。

古いデバイスでインストールリファラーを収集するには:

既存のインストールリファラー受信機がある場合:

あなたのアプリには、AndroidからINSTALL_REFERRERを受信するBroadcastReceiverがすでにある可能性があります。

その場合は、BroadcastReceiverのonReceiveメソッドに次の行を追加します:

new SingularInstallReceiver().onReceive(context, intent);

例えば、既存のレシーバーがMyCustomInstallReceiverという名前の場合、以下のようになります:

public class MyCustomInstallReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        // インストールのリファラー情報をSingularに渡す
        new SingularInstallReceiver().onReceive(context, intent);
        // ...
    }
}

他にインストール・リファラ・レシーバがない場合:

アプリにインストールリファラーレシーバーがない場合は、マニフェストファイルの<application>タグに次の行を追加するだけで、Singular SDKに唯一のレシーバーを登録させることができます:

<receiver android:exported="true" android:name="com.singular.sdk.SingularInstallReceiver">
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>

4.5.セッションの管理

Android API 14 (Ice Cream Sandwich) 以上では、Singular SDKはセッション管理を自動的に行うことができます。アプリの minSdkVersion が 14 以上の場合、セッション管理に追加の設定は必要ありません。

セッションタイムアウトの変更

デフォルトでは、アプリがバックグラウンドで60秒以上実行されてからフォアグラウンドに戻ると、SDKは新しいセッションを登録します。

タイムアウト値を変更するには、SDKを初期化する前にSingularConfigで withSessionTimeoutInSec(<timeout in seconds>)を使用します。

// セッションのタイムアウトを120秒に設定
SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")
.withSessionTimeoutInSec(120); 

手動セッション管理

アプリのminSdkVersionが14以下の場合、SingularのSDKの2つのセッション処理メソッド、onActivityPausedと onActivityResumedを各アクティビティから呼び出して、セッションを手動で管理する必要があります。

注: 他のすべてのアクティビティが派生している共通の基本アクティビティクラスがある場合、onActivityResumedとonActivityPausedの呼び出しを共通アクティビティの "onResumeとonPauseメソッド "に置くことができます。

Singular.onActivityResumedメソッド
説明 アクティビティのonResumeメソッド内でこのメソッドを呼び出し、Singularセッションを管理します。
シグネチャ public static void onActivityResumed()
使用例
@Override
protected void onResume() {
    super.onResume();
    Singular.onActivityResumed();
    .... //その他のコードがある場合
}
Singular.onActivityPausedメソッド
説明 アクティビティのonPauseメソッド内でこのメソッドを呼び出し、Singularセッションを管理します。
シグネチャ public static void onActivityPaused()
使用例
@Override
protected void onPause() {
    super.onPause();
    Singular.onActivityPaused();
    .... //その他のコードがある場合
}

4.6.JavaScript インターフェイスの使用

SingularはJavaScriptインターフェイスを提供しており、アプリ内のJavaScriptコードからSingularを呼び出すために使用できます。

例えば、JavaScript インターフェースを設定すると、JavaScript コードから Singular に以下のようにイベントを送ることができます:

イベントの例

SingularInterface.event('event');
SingularInterface.event('test',
JSON.stringify({"a1":"bar", "a2":"boo", "a3":"baz"}));

このインターフェースは以下のSDKメソッドをサポートしています:

  • setCustomUserID
  • unsetCustomUserID
  • event
  • revenue

JavaScriptインターフェースを有効にするには、メインアクティビティに以下のコード行を追加してください。

SingularJSInterface singularJSInterfaceInstance = new SingularJSInterface(this);
singularJSInterfaceInstance.setWebViewId(R.id.webview);
myWebView.addjavascriptInterface(singularJSInterfaceInstance, "SingularInterface");

注意

  • 複数のウェブビューがある場合は、それぞれのウェブビューに対してこの操作を行ってください。
  • アプリケーションのonCreateメソッドにコードを配置することをお勧めします。

onCreateメソッドは以下のようになります:

public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    WebView myWebView = (WebView) this.findViewById(R.id.webview);
    WebSettings webSettings = myWebView.getSettings();
    webSettings.setjavaScriptEnabled(true);
    myWebView.loadUrl("file:///android_asset/index.html");

    SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");
    Singular.init(this, config);
    SingularJSInterface singularJSInterfaceInstance = 
        new SingularJSInterface(this);
    singularJSInterfaceInstance.setWebViewId(R.id.webview);
    myWebView.addjavascriptInterface(singularJSInterfaceInstance,
        "SingularInterface");
}

4.7.OAID(オープン広告ID)の収集

Google Playを使用していない国では、Android端末はGoogle Advertising ID(GAID、SingularではAIFAとも呼ばれる)を持っていません。その代わりに、端末からのセッションやイベントを追跡するために使用できるOAID(Open Advertising Identifier)と呼ばれる識別子を端末が提供している場合があります。

OAIDは現在、ファーウェイやMSA(Mobile Security Alliance)に属するブランドのデバイスで提供されています。

アプリがOAIDを収集するには、まずMSA SDKと Huawei OAID SDKを統合する必要があります。 OAIDを提供するすべてのプラットフォームでOAIDを収集できるようにするには、両方のSDKを統合する必要があります。

次に、トラッキングにOAIDを使用するようSingular SDKに指示するため、Singularを初期化する前にconfigオブジェクトにwithOAIDCollectionの呼び出しを追加します。

SingularConfig config = new SingularConfig("SDK KEY","SDK SECRET")
    .withOAIDCollection();
Singular.init(context, config);

Singular SDKは、デバイスがOAIDを持っているかどうか、またどのOAID SDKを使って識別子を収集すべきかを自動的に検出します。

4.8.IMEI番号の収集

アプリがGoogle Playを使用しない国で提供される場合、デバイスにはGoogle Advertising IDがありません。この場合、代わりに端末のIMEI(International Mobile Equipment Identity)を収集するとよいでしょう。

注意:Google Playサービスを利用している場合、IMEI番号の収集はGoogle Playサービスの規約違反となるため、行うべきではありません。

IMEI番号を収集するには

アプリのAndroidManifest.xmlファイルにandroid.permission.READ_PHONE_STATEパーミッションを追加する:

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

以下のようなコードを追加して、デバイスのIMEI番号を取得します:

TelephonyManager telephonyManager = (TelephonyManager)getSystemService(Context.TELEPHONY_SERVICE);

String imei = null;

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    imei = telephonyManager.getImei();
} else {
    imei = telephonyManager.getDeviceId();
}

IMEI番号をSingularに送信するには、以下のいずれかの方法を使用する:

推奨: 次の例のように、Singular SDKを初期化する前にwithIMEIを使って SingularConfigにIMEI番号を設定します。これにより、最初のセッションからSingularがIMEI番号を利用できるようになります。

SingularConfig config = new SingularConfig("SDK KEY","SDK SECRET")
.withIMEI("537769845792516"); Singular.init(context, config);

SDKの初期化後のコードの任意の時点でIMEI番号を設定するには、setIMEIを呼び出します。

Singular.setIMEIメソッド
説明 デバイスのIMEI番号をSingularに送信します。
シグネチャ public void setIMEI(string IMEIString)
使用例
Singular.setIMEI(IMEIString);

4.9.データプライバシー法の遵守

Singularは、GDPRやCCPA(カリフォルニア州消費者プライバシー法)のような消費者プライバシー法を遵守する可能性のあるパートナーと協力できるように、プライバシー保護機能を提供します。 これらのパートナーは、エンドユーザーが個人情報の共有に同意した場合に通知されることを望んでいます。

ユーザーに情報共有の同意を求める方法を実装している場合は、limitDataSharingメソッドを使用してユーザーの選択をSingularに通知します:

Singular.limitDataSharing(false)を使用して、ユーザが情報の共有に同意した(オプトインした)ことを示します。

ユーザが同意しなかった場合はSingular.limitDataSharing(true)を使用します。

Singularは"ユーザープライバシーのポストバック"でLimitDataSharingを使用し、関連する規制を遵守するために必要なパートナーにこの情報を渡します。詳しくは「ユーザーのプライバシーとデータ共有の制限」をご覧ください。

注: このメソッドの使用は任意ですが、ユーザーがオプトインしたことが特に通知された場合に限り、パートナーがSingularと共有する属性情報がある場合があります。

Singular.limitDataSharingメソッド
シグネチャ Singular.limitDataSharing(booleanshouldLimitDataSharing)
説明 個人データの共有に対するユーザーの同意(オプトイン)をSingularに通知します。
使用例
// ユーザーがデータ共有に同意した
Singular.limitDataSharing(false);

GDPR準拠のための追加メソッド

Singular SDKは、GDPRポリシーに準拠し、トラッキングに対するユーザーの同意または非同意についてSingularに知らせるためのメソッドをいくつか提供しています。

Singular.trackingOptInメソッド
説明 トラッキングに対するユーザーの同意(オプトイン)をSingularに通知します。
使用例
Singular.trackingOptIn();
Singular.stopAllTracking メソッド
説明

このアプリにおけるこのユーザーのトラッキングをすべて停止します。

注意:このメソッドを呼び出すと、アプリが再起動した後でもSDKが効果的に無効になります(状態は持続します)!トラッキングを再び有効にする唯一の方法は、resumeAllTracking()を呼び出すことです。
使用例
Singular.stopAllTracking();
Singular.resumeAllTrackingメソッド
説明 このアプリのこのユーザーのトラッキングを再開します。
使用
Singular.resumeAllTracking();
Singular.isAllTrackingStoppedメソッド
説明 このアプリのこのユーザーのトラッキング状況を確認します。StopAllTracking()を使用してトラッキングが停止され、再開されていない場合はtrueを返します。
使用例
Singular.isAllTrackingStopped();