新しいビデオガイド
統合プロセスの詳細については、このビデオをご覧ください。ビデオと以下のガイドの両方を使用することをお勧めします。
始める前にSDKの前提条件
Singular SDKの統合の手順に従ってください:計画と前提条件。
これらのステップはSingular SDKを統合するための前提条件です。
1.プロジェクトへのSDKの追加
1.1 Gradleを使用したSDKの追加
注:Gradle 7以降、Androidは プロジェクトやモジュールレベルの build.gradle 宣言よりもsettings.gradleの集中リポジトリ宣言を使用することを推奨しています 。
-
SingularのSDKリポジトリを settings.gradleファイルに追加します:
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven{ url = uri("https://maven.singular.net/") } } }
または古いバージョンのGradleでは、Singular SDKリポジトリをproject/build.gradleファイルに追加します:
repositories { mavenCentral() maven { url 'https://maven.singular.net/' } }
-
app/build.gradleの依存関係リストにSingularライブラリを追加します:
dependencies { ... implementation 'com.google.android.gms:play-services:6.5.87' implementation 'com.singular.sdk:singular_sdk:12.7.0' ... }
さらに、アプリがSamsung Galaxy Storeを通じて配布される場合は、Samsung Galaxy Storeのインストールリファラーをサポートするために以下を追加します:
dependencies { ... implementation 'store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0' ... }
-
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' ... }
-
アプリが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をダウンロードします。
- SDKパッケージを解凍し、Singular.aarをAndroidプロジェクトのlibsディレクトリに追加します。存在しない場合は、プロジェクトフォルダ(通常は<project>/app/libs)にlibsというディレクトリを作成します。
プロジェクトの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.7.0</version>
</dependency>
EclipseのAARプラグインを使うことができます: gradle-eclipse-aar-plugin
プラグインを使いたくない場合は、以下の手順に従ってください:
- singular_sdk-12.7.0.aar を解凍します。
- classes.jarをsingular_sdk-12.7.0.jarにリネームします(これがメインのSDK jarです)。
- com.android.installreferrer:installreferrer:2.2」ライブラリを、お好みの方法でプロジェクトに追加します。
- AARに含まれるAndroidManifest.xmlからBIND_GET_INSTALL_REFERRER_SERVICEパーミッションをAndroidManifest.xmlにコピーします。
- AARに含まれるAndroidManifest.xmlからCHECK_LICENSEパーミッションをAndroidManifest.xmlにコピーします。
proguard.configファイルに以下のコードを追加します:
-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
# Uncomment this line in case your are calling the 'revenue' function using the Google billing library
#-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" />
Note:アプリのビルドが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>
2.基本的なSDK統合の設定
注:Singular SDKを実装する際には、GDPR、CCPA、COPPAなど、お客様がビジネスを展開している地域で制定されている様々なプライバシー法を遵守することを忘れないでください。詳しくはSDKのオプトインとオプトアウトをご覧ください。
2.1.Singularライブラリのインポート
Singularライブラリをインポートするには、以下のインポートをMainActivityファイルに追加します:
import com.singular.sdk.*;
import com.singular.sdk.*
2.2.構成オブジェクトの構築
SDKを初期化する前に、SingularConfigオブジェクトを作成する必要があります。このオブジェクトには以下が含まれます:
- SDKキーと SDKシークレット(これらを取得するには、Singularアカウントにログインし、DEVELOPER TOOLS > SDK Integration > SDK Keysに進みます)。
- 任意で設定したいSDK設定。
- METAインストールリファラー帰属のサポート
Meta Install Referrer」アトリビューションを有効にするために必要なSDK設定:
- Singular Configuration ObjectにFacebookアプリIDを入力してください。
// To enable META Install Referrer config.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");
- Singular Configuration ObjectにFacebookアプリIDを入力してください。
以下のコード例では、Singular SDKを初期化する前に設定オブジェクトを作成し、共通の設定オプションを設定しています。
以下のセクションでは、これらのオプションの詳細とカスタマイズ方法について説明します。
@Override
protected void onCreate(Bundle savedInstanceState) {
...
// Create a configuration object
SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");
// Set up a deep links handler
config.withSingularLink(
getIntent(),
new SingularLinkHandler() {
@Override
public void onResolved(SingularLinkParams params) {
String deeplink = params.getDeeplink();
String passthrough = params.getPassthrough();
boolean isDeferred = params.isDeferred();
// Add deep link handling code here
}
}
);
Singular.init(context, config);
...
}
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Create a configuration object
val config = SingularConfig("SDK KEY", "SDK SECRET")
// Set up a deep links handler
config.withSingularLink(
intent
) { params ->
val deeplink = params.deeplink
val passthrough = params.passthrough
val isDeferred = params.isDeferred
// Add deep link handling code here
}
Singular.init(this, config)
...
}
下の表は、アプリにオプションや機能を追加するために 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ハンドラ) |
(新しい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.ディープ・リンク・サポートの追加
ディープリンクは、ユーザーをアプリ内の特定のコンテンツに誘導するURLです。アプリがすでにインストールされているデバイスでユーザーがディープリンクをタップすると、アプリは目的の製品ページまたはエクスペリエンスに直接開きます。Singularトラッキングリンクは、ディープリンクとディファードディープリンクの両方をサポートしています。詳しくは、ディープリンクFAQと シンギュラーリンクFAQをご覧ください。
必要条件
-
アプリでディープリンクを有効にするには、Singular Links Prerequisitesを完了していることを確認してください。
-
シンギュラーリンクハンドラの実装
Singular リンクハンドラは、Singular トラッキングリンクからディープリンク (_dl)、ディファードディープリンク (_ddl)、パススルー (_p)パラメータを取得するコールバックメカニズムを提供します。これらのパラメータは、アプリが開かれた時(既にインストールされている場合)、またはアプリがインストールされた後に渡されます。
Singular コンフィグオブジェクトを更新する
SDKの初期化中にSingularLinkHandlerコールバックをSingularConfigオブジェクトに追加し、入力されるディープリンクと遅延ディープリンクデータを処理します。
テスト用にログをインラインで追加します。
// Call SingularLinkHandler config.withSingularLink(getIntent(), new SingularLinkHandler() { @Override public void onResolved(SingularLinkParams params) { Log.d("Singular", "SingularLinkHandler"); String deeplink = params.getDeeplink(); String passthrough = params.getPassthrough(); boolean isDeferred = params.isDeferred(); // Add deep link handling code here Log.d("SingularLink", "Deeplink: " + deeplink); Log.d("SingularLink", "Passthrough: " + passthrough); Log.d("SingularLink", "Is Deferred: " + isDeferred); } } );
// Call SingularLinkHandler config.withSingularLink(intent) { singularLinkParams -> Log.d("Singular", "SingularLinkHandler") val deeplink = singularLinkParams.deeplink val passthrough = singularLinkParams.passthrough val isDeferred = singularLinkParams.isDeferred // Add deep link handling code here Log.d("Singular", "Deeplink: $deeplink") Log.d("Singular", "Passthrough: $passthrough") Log.d("Singular", "isDeferred: $isDeferred") }
注意: SingularLinkHandlerは、アプリがSingularリンクを通して開かれたときにのみトリガーされます。詳しくは( Singular Links FAQを参照してください)を参照してください。
SingularLinkHandler の動作に関する注意事項:SingularLinkHandlerの動作に関する注意事項:
-
新規インストールでは、アプリの起動時にOpen URL がありません。そのため、Singularは最後のタッチ(クリック)までのアトリビューションを完了し、トラッキングリンクにディープリンクまたはディファードディープリンク(DDL)の値が含まれているかどうかを判断する必要があります。このプロセスは、Singular SDKが最初のセッションをSingularサーバーに送信するときに発生します。該当する場合、ディープリンク値はdeeplinkパラメータでSDKのSingularLinkHandlerに返されます。
このシナリオをテストするには
- デバイスからアプリをアンインストールします(現在インストールされている場合)。
- Google Advertising ID(GAID)をリセットします。
- デバイスからDDLが設定されたSingularトラッキングリンクをクリックします。
- アプリをインストールして開きます。
アトリビューションが正常に完了し、DDLの値がアプリに渡されます。
- トラッキングリンクにpassthrough (_p)パラメータが含まれている場合、SingularLinkHandler の passthroughパラメータには対応するデータが含まれます。これはアプリ内のクリックから追加データを取得するのに便利です。
- アプリがすでにインストールされている場合、Singularリンクをクリックするとアプリが開きます。SingularはAndroid App Linksテクノロジーを使ってこれを実現します。Android OSはSingularトラッキングリンク全体を含むOpen URLを提供します。SDKの初期化中に、Singular SDKはAndroidIntentを解析し、ディープリンクと パススルーの値を抽出し、SingularLinkHandlerを通して返します。
-
高度なオプション
非Singularディープリンクの処理
デフォルトでは、Singular SDKは非Singularディープリンクをサポートしています。これはGoogle Adsのようなパートナーからのアトリビューションやリエンゲージメントを測定するために必要です。
Android SDKバージョン12.1.1から、Singular以外のユニバーサルリンクが自動的にサポートされるようになりました。このバージョン以降を使用している場合、サードパーティ製リンクをサポートするための追加設定は必要ありません。
遅延ディープリンクタイムアウトの変更(オプション)
デフォルトでは、アプリが開き、Singular SDKが最初のセッション(インストールセッション)をSingularサーバーに送信すると、サーバーはユーザーにアプリのインストールを促したトラッキングリンクに関連する遅延ディープリンクがあるかどうかをチェックします。アトリビューションが成功した場合、遅延ディープリンクの値がSDKセッションレスポンスに返され、Singular Link Handlerによって処理されます(遅延ディープリンクとはを参照してください)。
60秒以内に遅延ディープリンクが見つからない場合、サーバーは検索を停止し、遅延ディープリンク値を返しません。このタイムアウト値を変更するにはwithDDLTimeoutInSec
パラメータで変更できます。
以下の例では、タイムアウトを30秒に変更しています:
config.withDDLTimeoutInSec(30);
.withDDLTimeoutInSec(30)
2.4.Singularの初期化
Singular SDKはアプリを開くたびに初期化する必要があります。これはSingularのすべてのアトリビューション機能の前提条件であり、また新しいユーザーセッションをSingularに送信します(セッションはユーザーのリテンションを計算するために使用されます)。
Singularを初期化するには、以下のコードを使います:
Singular.init(context, config);
Singular.init(context, config)
パラメータ | 説明 |
コンテキスト context | アプリケーションクラスから、コンテキストとしてthisまたはgetApplicationContext()を渡すことができます。アクティビティ内からアプリケーションコンテキストを取得するには、currentActivity.getApplicationContext()を呼び出します。 |
SingularConfig コンフィグ | 前のステップで作成したSingularConfigオブジェクト。 |
init メソッドはアプリのどの時点でも呼び出すことができますが、イベントが報告される前に呼び出す必要があります。メインアクティビティのonCreate メソッドや、ディープリンク経由で直接開かれるアクティビティでinit を呼び出すことをお勧めします。
注意:ディープリンクで開かれるアクティビティ内では、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.unsetCustomUserID メソッド | |
説明 | Singularに送信されたユーザーIDの設定を解除します。 |
シグネチャ | public void unsetCustomUserId() |
使用例 |
|
重要:この高度なエンタープライズ機能は例外的な場合にのみ利用できます。実装する前にSingularのソリューションエンジニアにご相談ください。
Singularはサーバー間の統合により、追加のモバイルイベント追跡データを受け取ることができます。この機能を利用するには、ユーザーIDをSingularのモバイルデバイス追跡識別子にマッピングする必要があります。
注意:Singular SDKを初期化した後、またはユーザーIDを取得した後、できるだけ早くこのメソッドを呼び出してください。
Singular.setDeviceCustomUserId メソッド | |
---|---|
説明 | ログイン時と同じカスタムユーザーIDを設定し、Singularのトラッキング識別子にマッピングします。 |
シグネチャ | public void setDeviceCustomUserId(string customUserId) |
使用例 |
|
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) |
使用例 |
|
初期化後のグローバル・プロパティの設定
アプリの実行中にいつでもグローバル・プロパティを設定、解除、取得するには、以下のメソッドを使用します。
Singular.setGlobalProperty メソッド | |
---|---|
説明 |
グローバル・プロパティを指定された値に設定します。 注意事項
|
シグニチャ | public static bool setGlobalProperty(String key, String value, boolean overrideExisting) |
使用例 |
|
Singular.getGlobalProperties メソッド | |
説明 | すべてのグローバル・プロパティとその現在の値を Map として取得します。 |
シグネチャ | public static Map<String, String> getGlobalProperties() |
使用例 |
|
Singular.unsetGlobalProperty メソッド | |
説明 | グローバル・プロパティを削除する。 |
シグネチャ | public static void unsetGlobalProperty(String key) |
使用例 |
|
Singular.clearGlobalProperties メソッド | |
説明 | すべてのグローバル・プロパティを削除します。 |
シグネチャ | public static void clearGlobalProperties() |
使用例 |
|
3.イベントと収益のトラッキング
3.1.イベントのトラッキング(非収益)
Singularはアプリ内イベントに関するデータを収集し、キャンペーンのパフォーマンス分析やKPIの測定に役立てることができます。例えば、ゲームアプリでユーザーのログイン、登録、チュートリアルの完了、レベルアップなどのデータを収集したい場合があります。
標準イベントと属性とは何ですか?
Singularは様々な標準イベントをサポートしています。これらのよく使われるイベントは、レポートや最適化のために広告ネットワークでよくサポートされています。もう一つの利点は、標準イベント名を使用すると、Singularが自動的に認識し、手動で定義しなくてもイベントリストに追加されることです。可能な限り標準イベントを使用することをお勧めします。
Singularに送信されるイベントリスト(付随する属性付き)は、UA/マーケティング/ビジネスチームが組織のマーケティングKPIに基づいて作成する必要があります。ビジネスチームは、How to Track In-App Eventsのガイドに従ってください:Guide For Singular Attribution Customers.
追跡するイベントごとに、さまざまな属性を渡すことができます。イベントごとの推奨標準属性を参照してください。
イベントの送信
コード内で、eventJSONまたはeventメソッドを使用してSingularにイベントを送信します(読みやすさのためにeventJSONを推奨します)。
- 標準イベントの場合は、Android SDK の標準イベントと属性のリストに表示されているイベントの Android 名を使用します(例:sngTutorialComplete)。以下のコード例を参照してください。
- カスタムイベント(Singularの標準イベントと一致しない、あなたの組織が測定したいイベント)を送信する場合は、制限に準拠した任意の文字列を使用してください。
Singular.eventJSON メソッド | |
---|---|
説明 | ユーザーイベントをJSONObject形式で追加情報と共にSingularに報告します。 |
シグネチャ |
Singular.eventJSON(String name, JSONObject args)
Note: 'args' is a JSONObject containing one or more key-value pairs. The key is a string and the value can be any type that's allowed as a JSONObject value.
|
使用例 |
|
Singular.event メソッド | |
説明 | 追加情報の有無にかかわらず、ユーザーイベントをSingularに報告します。 |
シグネチャ |
Singular.event(String eventName) Note: 'args' is one or more key-value pairs (see the example below). The key is a string and the value can be any type that's allowed as a JSONObject value (i.e., JSONObject, JSONArray, String, Boolean, Integer, Long, Double or NULL). The 'args' list must contain an even number of elements or the event will be rejected by Singular. |
使用例 |
|
注意事項
- サードパーティのパートナーや分析ソリューションを使用する場合は、互換性を保証するためにイベント名と属性を英語で渡すことを強くお勧めします。
- イベント名は 32 ASCII 文字に制限されています。非ASCII文字の文字列は、UTF-8に変換された後、32バイト以下にする必要があります。
- 属性と値は500 ASCII文字に制限されます。
3.2.収益のトラッキング
Singularは、アプリ内課金(IAP)、サブスクリプション、カスタム収益から収益イベントを取得し、キャンペーンのパフォーマンスと広告費用対効果(ROAS)を測定します。収益データは3つの主要なチャネルを通じて入手できます:
- Singularダッシュボードのインタラクティブレポート
- カスタム分析用の詳細なエクスポートログとETLデータ送信先
- 外部プラットフォームへのリアルタイムポストバック
この包括的な収益追跡により、マーケティング費用とキャンペーンの最適化に関するデータ主導の意思決定が可能になると同時に、データの利用方法と分析方法に柔軟性が生まれます。
要件
- カスタム収益イベント名を使用する場合、カスタム収益イベント名は32 ASCII文字に制限されます。非ASCII文字の場合、UTF-8に変換すると32バイトに制限されます。
- イベント属性名と属性値は 500 ASCII 文字に制限されます。
-
通貨を3文字のISO 4217通貨コードとして渡します:
USD, EUR, INR
ベストプラクティス
- Singularは、Singularの標準的なイベント名と属性名を使用してイベントを渡すことを推奨します。
- カスタム収益イベント名を使用する場合は、アドネットワークのポストバックとの互換性を高めるために英語で送信する必要があります。
- 収益イベントは、収益額が0より大きいか小さい場合にのみSingularに送信されます。
収益トラッキングの実装
サブスクリプション以外のアプリ内課金
収益イベントをSingularに報告するには、Google Billing Libraryから受け取ったPurchaseオブジェクトをrevenueまたはcustomRevenueSDKメソッドに渡します。これには2つの利点があります:
- Singularはトランザクションの詳細をすべて取得するので、Singularのレポートが充実します。
- SingularはGoogleからトランザクションのレシートを受け取るので、アプリ内詐欺対策としてトランザクションの検証に使用できます。
注意事項
- customRevenueにカスタムイベント名を渡すと、Singularのレポートで収益を収益イベントの種類ごとに分けて表示できるようになります。
- 異なる通貨で報告された収益は、Singularアカウントで設定された組織の優先通貨に自動変換されます。
収益方法
収益イベントをPurchaseオブジェクトでSingularに送信します。
署名
Singular.revenue(String currency, double amount, Object purchase)
使用例
Singular.revenue("USD", 5.50, purchase);
Singular.revenue("USD", 5.50, purchase)
customRevenue メソッド
カスタムイベント名とPurchaseオブジェクトで収益イベントを Singular に送信します。
シグネチャ
Singular.customRevenue(String eventName, String currency, double amount, Object purchase)
使用例
Singular.customRevenue("MyCustomRevenue", "USD", 5.50, purchase);
Singular.customRevenue("MyCustomRevenue", "USD", 5.50, purchase)
サブスクリプション収益
サブスクリプションのトラッキング
Singularを使えば、アプリ内で定期購入や更新をトラッキングすることができ、ユーザーの行動や収益生成に関する洞察を得ることができます。Singular SDKを使ってサブスクリプションイベントを実装する方法については、包括的なガイドをご覧ください。[購読イベント技術実装ガイド]
購入検証なしのカスタム収益
上記の方法で収益イベントを報告することを強く推奨しますが、購入オブジェクトを渡さずに 収益と customRevenueを使用することもできます。その代わりに、トランザクションの通貨と金額、そしてオプションで商品の詳細を渡します。
customRevenueメソッドでは、カスタム・イベント名を渡すこともできます。
これらのメソッドを使用した場合、Singular はトランザクションのレシートを取得せず、トランザクションを検証できないことに注意しましょう。
revenue メソッド
収益金額、通貨、オプションの詳細を含む収益イベントを Singular に送信します。
署名
Singular.revenue(String currency, double amount)
Singular.revenue(String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice)
Singular.revenue(String currency, double amount, Map<String, Object> attributes)
使用例
商品詳細なし
Singular.revenue("USD", 5.50);
商品詳細あり
Singular.revenue("EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee" , 1, 5.00);
属性マップ内の商品詳細
Map<string, object="Object"> attributes = new HashMap<>();
attributes.put("product_id", "com.app.premium");
attributes.put("transaction_id", "T12345");
attributes.put("quantity", 1);
attributes.put("is_trial", false);
// Call the revenue method
Singular.revenue("USD", 9.99, attributes);
商品詳細なし
Singular.revenue("USD", 5.50)
商品詳細あり
Singular.revenue("EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee" , 1, 5.00)
属性マップに商品詳細あり
val attributes = mutableMapOf<String, Any>().apply {
put("product_id", "com.app.premium")
put("transaction_id", "T12345")
put("quantity", 1)
put("is_trial", false)
}
// Call the revenue method
Singular.revenue("USD", 9.99, attributes)
customRevenue メソッド
イベント名、収益額、通貨コード、追加のトランザクション属性を指定して、カスタム収益イベントをSingularに送信します。Singularはこれらのイベントを処理してアプリ内収益をトラッキングします。
シグネチャ
Singular.customRevenue(String eventName, String currency, double amount)
Singular.customRevenue(String eventName, String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice)
Singular.customRevenue(String eventName, String currency, double amount, Map<String, Object> attributes)
使用例
商品詳細なし
Singular.customRevenue("MyCustomRevenue", "USD", 5.50);
商品詳細あり
Singular.customRevenue("MyCustomRevenue", "EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee" , 1, 5.00);
属性マップに商品詳細がある場合
Map<string, object="Object"> attributes = new HashMap<>();
attributes.put("product_id", "com.app.premium");
attributes.put("transaction_id", "T12345");
attributes.put("quantity", 1);
attributes.put("is_trial", false);
// Call the revenue method
Singular.customRevenue("MyCustomRevenue", "USD", 9.99, attributes);
商品詳細なし
Singular.customRevenue("MyCustomRevenue", "USD", 5.50)
商品詳細あり
Singular.customRevenue("MyCustomRevenue", "EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee" , 1, 5.00)
属性マップに商品詳細あり
val attributes = mutableMapOf<String, Any>().apply {
put("product_id", "com.app.premium")
put("transaction_id", "T12345")
put("quantity", 1)
put("is_trial", false)
}
// Call the revenue method
Singular.customRevenue("MyCustomRevenue", "USD", 9.99, attributes)
3.3.ハイブリッドイベントトラッキング(上級者向け)
Singularでは、アプリに統合されたSingular SDKを通してすべてのイベントと収益を送信することを推奨しています。しかし、Singularは他のソースからイベントや収益を収集することもできます。
Singular SDKから送信されないイベントは、SingularのServer-to-Server Event documentation requirementsに準拠し、イベントの属性を正しく設定するために一致するデバイス識別子を提供する必要があります。
重要です:
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のドキュメントをご覧ください。
4.詳細オプション
4.1.ショートリファラーリンクの作成
注:この機能はSDKバージョン12.1.1+で利用可能です。ショートリンクは、一度作成すると30日間有効です。
ショートリンクを使用すると、長くてパラメータがいっぱいのシンギュラーリンクを、共有に便利な短くて安全なリンクに変換できます。
通常、ショートリンクを動的に作成して、アプリのユーザーが友達と共有してアプリの使用を招待できるようにします。
ショートリンクを作成するには
- アプリのダウンロードにつながるシンギュラーリンク(シンギュラーリンクのFAQを参照)。
- リンクに動的に追加したいパラメータ(オプションの一覧はトラッキングリンクパラメータをご覧ください)。
- アプリの新規インストールを、リンクを共有したユーザーまで追跡したい場合は、参照ユーザーの名前とID。
以下の例のように、createReferrerShortLinkメソッドを使用してショートリンクを作成します。
// Create a JSON object to add parameters to the Singular Link (if they don't exist in the link URL yet)
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", // The original Singular Link URL
"Referrer Name",
"Referrer ID",
params,
new ShortLinkHandler() {
@Override
public void onSuccess(final String shortLinkURL) {
view.post(new Runnable() {
@Override
public void run() {
// Add your share logic here
}
});
}
@Override
public void onError(final String error) {
view.post(new Runnable() {
@Override
public void run() {
// Logic to retry/abort/modify the params passed to
// the function, based on the cause of the error
}
});
}
});
// Create a JSON object to add parameters to the Singular Link (if they don't exist in the link URL yet)
val params = JSONObject()
try {
params.put("channel", "sms")
params.put("another parameter", "parameter value")
} catch (e: JSONException) {
e.printStackTrace()
}
Singular.createReferrerShortLink(
"https://sample.sng.link/D52wc/cuvk?pcn=test", // The original Singular Link URL
"Referrer Name",
"Referrer ID",
params,
object : ShortLinkHandler {
override fun onSuccess(shortLinkURL: String) {
view.post(Runnable {
// Add your share logic here
})
}
override fun onError(error: String) {
view.post(Runnable {
// Logic to retry/abort/modify the params passed to
// the function, based on the cause of the error
})
}
})
広告収益の追加_アトリビューション_サポート
4.2.広告収入アトリビューションサポートの追加
SingularはGoogle AdMob、AppLovin、Unity LevelPlay (IronSource)、TradPlusなどの広告収益アトリビューション用のメディエーションプラットフォームと統合されています。また、Singularは一般的な広告収益SDKの統合により、他のメディエーションプラットフォームもサポートしています。
メディエーションプラットフォームから広告収益アトリビューションデータを取得するには、Singular SDKインテグレーションにコードスニペットを追加します。これにより、SKAdNetworkキャンペーンの広告収入データを取得することもできます。
メディエーションプラットフォームからユーザーレベルの広告収益を取得することで、Singularはこのデータを受け入れることができるメディアソースにアトリビューションされた広告収益を送り返し、AdROASキャンペーンを実施することができます。
SDKの実装方法とコードスニペットはこちら[HERE]をご覧ください。
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) {
// Pass install referrer information on to 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>)を使用します。
例
// Set the session timeout to 120 seconds
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() |
使用例 |
|
Singular.onActivityPaused メソッド | |
説明 | アクティビティのonPauseメソッド内でこのメソッドを呼び出し、Singularセッションを管理します。 |
シグネチャ | public static void 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
- イベント
- 収益
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) |
使用例 |
|
4.9.データプライバシー法の遵守
Singularは、GDPRやCCPA(カリフォルニア州消費者プライバシー法)などの消費者プライバシー法を遵守している可能性のあるパートナーに協力できるよう、プライバシー保護機能を提供しています。このようなパートナーは、エンドユーザーが個人情報を共有することに同意した場合に通知されることを望んでいます。
ユーザーに情報共有の同意を求める方法を実装している場合は、limitDataSharingメソッドを使用してユーザーの選択をSingularに通知します:
Singular.limitDataSharing(false)を使用して、ユーザが情報の共有に同意した(オプトインした)ことを示します。
ユーザが同意しなかった場合は、Singular.limitDataSharing(true)を使用します。
Singularは"ユーザープライバシーのポストバック"でLimitDataSharingを使用し、関連する規制を遵守するために必要なパートナーにこの情報を渡します。詳しくは「ユーザーのプライバシーとデータ共有の制限」をご覧ください。
注: このメソッドの使用は任意ですが、ユーザーがオプトインしたことが特に通知された場合にのみ、パートナーがSingularと共有する属性情報があるかもしれません。
Singular.limitDataSharingメソッド | |
---|---|
署名 | Singular.limitDataSharing(boolean shouldLimitDataSharing) |
説明 | プライベートデータの共有に対するユーザーの同意(オプトイン)をSingularに通知します。Limit Data Sharing メソッドは、アプリがユーザーデータを第三者に送信するかどうかを制御するオプションを提供します。これは、ユーザーの好みやプライバシー要件に基づいてデータ共有を制限したい場合に便利です。 |
使用例 |
|
GDPR準拠のための追加メソッド
Singular SDKは、GDPRポリシーに準拠し、トラッキングに対するユーザーの同意または非同意についてSingularに知らせるためのメソッドをいくつか提供しています。
Singular.trackingOptInメソッド | |
---|---|
説明 | トラッキングに対するユーザーの同意(オプトイン)をSingularに通知します。TrackingOptIn()メソッドは、Singularのサーバーに "gdpr "イベントを送信するために使用されます。このメソッドを呼び出さない場合、アプリはユーザーが同意したかのようにトラッキングを続けますが、特にGDPRオプトインとしてマークされることはありません。アプリがGDPR(一般データ保護規則)に準拠する必要がある場合は、ユーザーの同意が適切に記録されるように、この関数を呼び出す必要があります。 |
使用例 |
|
Singular.stopAllTrackingメソッド | |
説明 |
このアプリでこのユーザーのすべてのトラッキング活動を停止します。
注意:このメソッドを呼び出すと、アプリが再起動した後でもSDKが効果的に無効になります(状態は永続的です)!トラッキングを再度有効にする唯一の方法は、resumeAllTracking()を呼び出すことです。
|
使用例 |
|
Singular.resumeAllTrackingメソッド | |
説明 | このアプリのこのユーザーのトラッキングを再開します。 |
使用例 |
|
Singular.isAllTrackingStoppedメソッド | |
説明 | このアプリのこのユーザーのトラッキング状況を確認します。StopAllTracking()を使用してトラッキングが停止され、再開されていない場合はtrueを返します。 |
使用例 |
|