詳細オプション

インストールリファラー収集、セッション管理、JavaScript連携、および特殊なユースケース向けの 代替デバイス識別子を含む詳細なSDK機能を構成します。

インストールリファラー収集（レガシーデバイス）

概要

インストールリファラーは、ユーザーがGoogle Play Storeからアプリをインストールする前に クリックした広告を識別することで、正確なアトリビューションを提供します。

自動収集:

最新のGoogle Play Storeがインストールされたデバイスでは、Singular SDKがGoogle Play Referrer APIを使用してインストールリファラーを自動的に収集します。手動構成は レガシーデバイスのサポートにのみ必要です。

既存のレシーバーと統合する

アプリにすでに INSTALL_REFERRER 用の BroadcastReceiver がある場合は、インストールリファラーデータをSingularに転送します。

実装:

既存のレシーバーの onReceive メソッド内に SingularInstallReceiver の呼び出しを追加します。

class MyCustomInstallReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        // Forward install referrer to Singular
        SingularInstallReceiver().onReceive(context, intent)

        // Your existing logic
        // ...
    }
}

public class MyCustomInstallReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        // Forward install referrer to Singular
        new SingularInstallReceiver().onReceive(context, intent);

        // Your existing logic
        // ...
    }
}

Singularレシーバーを登録する

アプリに既存の INSTALL_REFERRER ハンドラーがない場合、Singularのインストールリファラーレシーバーを構成します。

AndroidManifest.xmlの構成:

<application>
    <!-- Other application components -->

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

セッション管理

自動セッション管理

Singular SDKは、Android API 14（Ice Cream Sandwich）以上で追加の構成なしに セッション管理を自動的に処理します。

デフォルトの動作:

アプリがバックグラウンドに60秒以上移動した後、フォアグラウンドに戻ると、SDKは 新しいセッションを登録します。

セッションタイムアウトを構成する

アプリの使用パターンに合わせてセッションタイムアウトの期間をカスタマイズします。

メソッドシグネチャ:

SingularConfig.withSessionTimeoutInSec(int timeoutInSeconds)

// Set session timeout to 120 seconds (2 minutes)
val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withSessionTimeoutInSec(120)

Singular.init(applicationContext, config)

// Set session timeout to 120 seconds (2 minutes)
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withSessionTimeoutInSec(120);

Singular.init(getApplicationContext(), config);

タイムアウト値:

• デフォルト: 60秒
• 最小: 0秒（すべてのバックグラウンド/フォアグラウンドへの 遷移で新しいセッションが作成されます）
• 推奨: アプリの使用パターンに応じて30〜180秒

手動セッション管理（API < 14）

minSdkVersion が14未満のアプリでは、各アクティビティでライフサイクルメソッドを呼び出して セッションを手動で管理します。

実装

各アクティビティのライフサイクルメソッドで onActivityResumed() と onActivityPaused() を呼び出すか、ベースアクティビティクラスで実装します。

class MainActivity : AppCompatActivity() {

    override fun onResume() {
        super.onResume()
        Singular.onActivityResumed()
        // Your other code
    }

    override fun onPause() {
        super.onPause()
        Singular.onActivityPaused()
        // Your other code
    }
}

public class MainActivity extends AppCompatActivity {

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

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

ハイブリッドアプリ向けのJavaScriptインターフェース

概要

SingularJSInterface を使用して、WebViewベースのハイブリッドアプリのJavaScriptコードからSingular SDK 機能を有効にします。

サポートされているメソッド:

• setCustomUserId: カスタムユーザー識別子を設定
• unsetCustomUserId: カスタムユーザー識別子を削除
• event: 属性の有無にかかわらずイベントをトラッキング
• revenue: 収益をトラッキング

WebView統合のセットアップ

Singular機能が必要な各WebViewに対して、アクティビティの onCreate() メソッドでJavaScriptインターフェースを構成します。

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    // Initialize Singular SDK
    val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    Singular.init(this, config)

    // Configure WebView
    val myWebView = findViewById<WebView>(R.id.webview)
    myWebView.settings.javaScriptEnabled = true
    myWebView.loadUrl("file:///android_asset/index.html")

    // Add Singular JavaScript interface
    val singularJSInterface = SingularJSInterface(this)
    singularJSInterface.setWebViewId(R.id.webview)
    myWebView.addJavascriptInterface(singularJSInterface, "SingularInterface")
}

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Initialize Singular SDK
    SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET");
    Singular.init(this, config);

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

    // Add Singular JavaScript interface
    SingularJSInterface singularJSInterface = new SingularJSInterface(this);
    singularJSInterface.setWebViewId(R.id.webview);
    myWebView.addJavascriptInterface(singularJSInterface, "SingularInterface");
}

JavaScriptの使用

WebViewで実行されるJavaScriptコードからSingularメソッドを呼び出します。

イベントをトラッキング

// Simple event without attributes
SingularInterface.event('level_completed');

// Event with attributes (pass as JSON string)
SingularInterface.event('purchase_attempt',
    JSON.stringify({
        "item_name": "sword",
        "item_category": "weapons",
        "item_price": 9.99
    })
);

収益をトラッキング

// Track revenue in USD
SingularInterface.revenue('USD', 9.99);

// Track revenue in other currencies
SingularInterface.revenue('EUR', 8.50);

カスタムユーザーIDを管理

// Set custom user ID
SingularInterface.setCustomUserId('user_12345');

// Remove custom user ID
SingularInterface.unsetCustomUserId();

代替デバイス識別子

OAID (Open Advertising ID)

Open Advertising Identifier (OAID) を使用して、Google Playのない地域のAndroid デバイスでトラッキングを有効にします。

OAIDサポート:

• Huaweiデバイス: Huawei独自のOAID実装
• MSAデバイス: Mobile Security Alliance加盟ブランド （OPPO、Vivo、Xiaomiなど）

前提条件

サポートされているすべてのプラットフォームでOAIDを収集するには、 MSA SDK と Huawei OAID SDK の両方を統合してください。

OAID収集を有効にする

トラッキングのためにOAIDを収集および使用するようにSingular SDKを構成します。

val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withOAIDCollection()

Singular.init(applicationContext, config)

SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withOAIDCollection();

Singular.init(getApplicationContext(), config);

IMEI (International Mobile Equipment Identity)

Google Play Servicesのない地域のデバイスでのトラッキングのために、デバイスのIMEI 番号を収集します。

必要な権限を追加

AndroidManifest.xmlに READ_PHONE_STATE 権限を追加します。

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

    <application>
        <!-- Your application components -->
    </application>
</manifest>

IMEI番号を取得する

適切なAPIレベル処理とともにTelephonyManagerを使用してデバイスのIMEIを取得します。

val telephonyManager = getSystemService(Context.TELEPHONY_SERVICE) as TelephonyManager

val imei: String? = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    telephonyManager.imei
} else {
    @Suppress("DEPRECATION")
    telephonyManager.deviceId
}

// Validate IMEI before use
if (imei != null && imei.isNotEmpty()) {
    // Send to Singular
    Log.d("IMEI", "Retrieved: $imei")
} else {
    Log.w("IMEI", "Failed to retrieve 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();
}

// Validate IMEI before use
if (imei != null && !imei.isEmpty()) {
    // Send to Singular
    Log.d("IMEI", "Retrieved: " + imei);
} else {
    Log.w("IMEI", "Failed to retrieve IMEI");
}

SingularにIMEIを送信する

SDK初期化中にIMEIを構成するか（推奨）、初期化後に動的に設定します。

オプション1: 構成メソッド（推奨）

// Set IMEI during initialization
val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withIMEI(imei)

Singular.init(applicationContext, config)

// Set IMEI during initialization
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withIMEI(imei);

Singular.init(getApplicationContext(), config);

オプション2: ランタイムメソッド

// Set IMEI after initialization
Singular.setIMEI(imei)

// Set IMEI after initialization
Singular.setIMEI(imei);