始める前にSDKの前提条件

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

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

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

1.1 Gradleを使用したSDKの追加

1. 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/' }
       }

2. 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'
         ...
         }

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+'
        ...
   }

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

<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>

-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" />

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

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

<queries>
   <package android:name="com.sec.android.app.samsungapps" />
</queries>

2.基本的なSDK統合の設定

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

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

import com.singular.sdk.*;

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 Configuration ObjectにFacebookアプリIDを入力してください。
      

      // To enable META Install Referrer
      
      config.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");

   アプリの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)
    ...
}

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

ディープリンクは、ユーザーをアプリ内の特定のコンテンツに誘導するURLです。アプリがすでにインストールされているデバイスでユーザーがディープリンクをタップすると、アプリは目的の製品ページまたはエクスペリエンスに直接開きます。Singularトラッキングリンクは、ディープリンクとディファードディープリンクの両方をサポートしています。詳しくは、ディープリンクFAQと シンギュラーリンクFAQをご覧ください。

必要条件

1. アプリでディープリンクを有効にするには、Singular Links Prerequisitesを完了していることを確認してください。

2. シンギュラーリンクハンドラの実装

   Singular リンクハンドラは、Singular トラッキングリンクからディープリンク (_dl)、ディファードディープリンク (_ddl)、パススルー (_p)パラメータを取得するコールバックメカニズムを提供します。これらのパラメータは、アプリが開かれた時（既にインストールされている場合）、またはアプリがインストールされた後に渡されます。

   ---

   Singular コンフィグオブジェクトを更新する

   SDKの初期化中にSingularLinkHandlerコールバックをSingularConfigオブジェクトに追加し、入力されるディープリンクと遅延ディープリンクデータを処理します。

   テスト用にログをインラインで追加します。

   JavaKotlin

   // 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に返されます。

     このシナリオをテストするには

     1. デバイスからアプリをアンインストールします（現在インストールされている場合）。
     2. Google Advertising ID（GAID）をリセットします。
     3. デバイスからDDLが設定されたSingularトラッキングリンクをクリックします。
     4. アプリをインストールして開きます。

     アトリビューションが正常に完了し、DDLの値がアプリに渡されます。

   • トラッキングリンクにpassthrough (_p)パラメータが含まれている場合、SingularLinkHandler の passthroughパラメータには対応するデータが含まれます。これはアプリ内のクリックから追加データを取得するのに便利です。
   • アプリがすでにインストールされている場合、Singularリンクをクリックするとアプリが開きます。SingularはAndroid App Linksテクノロジーを使ってこれを実現します。Android OSはSingularトラッキングリンク全体を含むOpen URLを提供します。SDKの初期化中に、Singular SDKはAndroidIntentを解析し、ディープリンクと パススルーの値を抽出し、SingularLinkHandlerを通して返します。

高度なオプション

config.withDDLTimeoutInSec(30);

.withDDLTimeoutInSec(30)

2.4.Singularの初期化

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

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

Singular.init(context, config);

Singular.init(context, config)

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

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

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

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

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

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

Singular.setCustomUserId("custom_user_id");

Singular.unsetCustomUserId();

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パラメータを使用します。

// Set two global properties and override any existing values

SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")
  .withGlobalProperty(“MyProperty”, “MyValue”, true)
  .withGlobalProperty(“AnotherProperty”, “AnotherValue”, true);

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

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

boolean result = Singular.setGlobalProperty(“MyProperty”, “MyValue”, true);

Map<String, String> map = Singular.getGlobalProperties();

Singular.unsetGlobalProperty(“MyProperty”);

Singular.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の標準イベントと一致しない、あなたの組織が測定したいイベント）を送信する場合は、制限に準拠した任意の文字列を使用してください。

// Example 1:

// Send the standard event sng_tutorial_complete with the

// recommended standard attributes


JSONObject att = new JSONObject();
try {
    att.put(Attributes.sngAttrContent.toString(), "Telugu");
    att.put(Attributes.sngAttrContentId.toString(), 32);
    att.put(Attributes.sngAttrContentType.toString(), "video");
    att.put(Attributes.sngAttrSuccess.toString(), 92);
} catch (JSONException e) {
    e.printStackTrace(); // Or log the exception


}
Singular.eventJSON(Events.sngTutorialComplete.toString(), att);

// Example 2:

// Send a custom event named "bonus_points_earned" with custom attributes

JSONObject att = new JSONObject();
try {
    att.put("Points", 500);
    att.put("score", 650);
} catch (JSONException e) {
    e.printStackTrace(); // Or log the exception


}
Singular.eventJSON("Bonus Points Earned", att);

// Example 1:

// Send the standard event sng_tutorial_complete with the

// recommended standard attributes


val att = JSONObject().apply {
    put(Attributes.sngAttrContent.toString(), "Telugu")
    put(Attributes.sngAttrContentId.toString(), 32)
    put(Attributes.sngAttrContentType.toString(), "video")
    put(Attributes.sngAttrSuccess.toString(), 75)
}
Singular.eventJSON(Events.sngTutorialComplete.toString(), att)

// Example 2:

// Send a custom event named "bonus_points_earned" with custom attributes

val att = JSONObject().apply {
    put("Points", 500)
    put("score",650)
}
Singular.eventJSON("Bonus Points Earned", att)

// Example 1:

// Send the standard event "Subscribe" (sng_subscribe) without any attributes

Singular.event(Events.sngSubscribe.toString());

// Example 2:

// Send the standard event "sng_tutorial_complete" with the 

//recommended standard attributes
Singular.event(Events.sngTutorialComplete.toString(),
    Attributes.sngAttrContent.toString(), "Spanish",
    Attributes.sngAttrContentId.toString(), 52,
    Attributes.sngAttrContentType.toString(), "video",
    Attributes.sngAttrSuccess.toString(), 46
);

// Example 3:

// Send a custom event named "SignUp" without any custom attributes

Singular.event("SignUp");

// Example 4:

// Send a custom event named "bonus_points_earned" with a custom attribute

Singular.event("Bonus Points Earned", "Points", 500);

// Example 1:

// Send the standard event "Subscribe" (sng_subscribe) with no attributes

Singular.event(Events.sngSubscribe.toString())

// Example 2:

// Send the standard event sng_tutorial_complete with the

// recommended standard attributes

Singular.event(Events.sngTutorialComplete.toString(),
    Attributes.sngAttrContent.toString(), "Telugu",
    Attributes.sngAttrContentId.toString(), "32",
    Attributes.sngAttrContentType.toString(), "video",
    Attributes.sngAttrSuccess.toString(), "yes"
)

// Example 3:

// Send a custom event named "SignUp" with no custom attributes

Singular.event("SignUp")

// Example 4:

// Send a custom event named "bonus_points_earned" with a custom attribute

Singular.event("Bonus Points Earned", "Points", 500)

3.2.収益のトラッキング

Singularは、アプリ内課金（IAP）、サブスクリプション、カスタム収益から収益イベントを取得し、キャンペーンのパフォーマンスと広告費用対効果（ROAS）を測定します。収益データは3つの主要なチャネルを通じて入手できます：

• Singularダッシュボードのインタラクティブレポート
• カスタム分析用の詳細なエクスポートログとETLデータ送信先
• 外部プラットフォームへのリアルタイムポストバック

この包括的な収益追跡により、マーケティング費用とキャンペーンの最適化に関するデータ主導の意思決定が可能になると同時に、データの利用方法と分析方法に柔軟性が生まれます。

要件

ベストプラクティス

収益トラッキングの実装

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

Singular.revenue("USD", 5.50, purchase);

Singular.revenue("USD", 5.50, purchase)

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.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)

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に準拠し、イベントの属性を正しく設定するために一致するデバイス識別子を提供する必要があります。

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

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.広告収入アトリビューションサポートの追加

4.3.アンインストールトラッキング

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

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メソッド "に置くことができます。

@Override
protected void onResume() {
    super.onResume();
    Singular.onActivityResumed();
    .... //other code if any
}

@Override
protected void onPause() {
    super.onPause();
    Singular.onActivityPaused();
    .... //other code if any
}

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メソッドは以下のようになります：

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(IMEIString);

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

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

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

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

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

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

// User has opted into sharing data

Singular.limitDataSharing(false);

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

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

Singular.trackingOptIn();

Singular.stopAllTracking();

Singular.resumeAllTracking();

Singular.isAllTrackingStopped();