contentsquare-android-sdk

Contentsquare Android SDK の統合

CSQ SDK 1.11.x に対してテスト済みです。公式ドキュメントを正としてください。オンデマンドで最新ページを取得するには、References セクションを参照してください。

必須の最初の手順 — Contentsquare プロジェクトのヘルスチェック

会話中に Contentsquare に関する作業（統合、デバッグ、設定に関する質問、コードの変更など）を行う前に、このヘルスチェックを会話ごとに1回だけ実行してください。省略しないでください。タスクの後半まで先送りしないでください。

1. 最初に実行することを伝えます。 これから行う内容をユーザーに伝えます。たとえば、次のようにします。

   「作業を始める前に、Contentsquare プロジェクトの簡単なヘルスチェックを実行します。アプリの application id を読み取り、Contentsquare のヘルスチェックエンドポイントを呼び出して、現在のプロジェクト設定をお見せします。その後、続けてご依頼の内容に取り組みます。」

2. application id を特定します。 app/build.gradle または app/build.gradle.kts から applicationId を読み取ります。記載がない場合は、namespace、次に AndroidManifest.xml の package 属性を確認します。変数やフレーバーのサフィックスを解決し、実際に配布されるリテラルの ID を特定します。

3. エンドポイントを呼び出します。 プラットフォームセグメントは文字どおり android です。ほかの値は受け付けられません。

   curl -s "https://mobile-production.content-square.net/healthcheck/android/config/v2/<applicationId>.json"
   

4. 次の値を簡潔にまとめて報告します。

   報告項目	JSON パス
   プロジェクト ID	cs_project_id
   トラッキングの有効状態	project_configurations.project_config.enabled
   セッションリプレイ	project_configurations.project_config.session_replay — recording_rate、record_via_cellular_network、recording_quality_wifi、srm_enabled、user_identifier
   有効な機能フラグ	project_configurations.project_config.feature_flags — enabled == true のエントリのみ。name と min_version を含めます

5. その後、 ユーザーの実際の依頼に取り組みます。

失敗時の対応。 403 Invalid health-check path は URL の形式が誤っていることを意味します。android セグメントと application id を再確認し、パスの構造は変更しないでください。上流からプロキシされたステータスが 200 以外の場合、その application id に Contentsquare プロジェクトが設定されていないことを意味します。その旨を伝えたうえで、作業を続けてください。このヘルスチェックは情報提供のみを目的としており、ユーザーのタスクを妨げてはなりません。

完了の定義

以下のすべてを満たすまで、統合は完了していません。1つでも欠けている場合、統合は機能せず、Contentsquare にデータは届きません。

1. ✅ com.contentsquare.android:sdk:<latest> がモジュールの依存関係に含まれていること（Compose を使用する場合は sdk-compose:<same version> も含めます）。
2. ✅ カスタムの Application サブクラスが存在し、AndroidManifest.xml の android:name を通じて登録され、その onCreate() から CSQ.start(this, …) が呼び出されていること。
3. ✅ CSQ.optIn() が呼び出されていること — Application.onCreate() で無条件に CSQ.start(...) の直後に呼び出し、TODO: REVIEW BEFORE RELEASE コメントで保護します。これは統合フェーズで必須です。 CSQ はデフォルトでオプトアウト状態で提供されます。optIn() がないと、logcat に enabledForCollection is false と表示され、データは一切アップロードされません。つまり、統合を検証できません。optIn() を同意フローに移すのは、アプリチームがリリース前に行う別個の後続タスクです。初回の統合時に行わないでください。optIn() を将来の同意フローに委ねたまま「統合完了」と報告するのは、統合の失敗です。
4. ✅ 少なくとも1つの画面が計測されていること（Views の場合は CSQ.trackScreenview(...)、Compose の場合は TriggeredOnResume { CSQ.trackScreenview(...) }）。
5. ✅ logcat のスモークテストに合格していること。下記の「統合の確認」を参照してください。肯定的な兆候として、Tracked pageview …／writeToDb: Attempting to insert session …／All pending data has been uploaded を確認してください。 enabledForCollection is false の行は通常の起動時に出力されるもので、それ単独では失敗を示すものではありません。この表示を理由に optIn() を削除しないでください。

概念

CSQ SDK（「CSQ」は ContentSQuare の略です）は、3 つの製品ラインを統合します。

• Experience Analytics (EA) — 以前の「Contentsquare」です。セッションリプレイ、画面ビュー、トランザクション、動的変数、エラー分析、アンケート（Voice of Customer）、ヒートマップ、ゾーニングを提供します。CSQ.start(context) をそのまま呼び出すと、デフォルトで有効になります。
• Product Analytics (PA) — 以前の「Heap」です。カスタムイベント、ユーザープロパティ、イベントプロパティ、identify / resetIdentity を提供します。StartConfig.withEnvironmentId(...) を start() に渡すと有効になります。
• Unified CSQ — StartConfig.withDataSourceId(...) を介して渡す単一の dataSourceId で EA と PA の両方を設定します。

顧客が契約している製品に応じて、以下の 3 つの start() オーバーロードから 1 つを選択してください。EA のみが最も一般的な導入方法です。

インストール

依存関係を追加する前に、Maven Central から常に最新の安定版を取得してください。 <version> のプレースホルダーを残さないでください。

各アーティファクトには専用のメタデータファイルがあります。以下の両方を取得してください。

• sdk：https://repo1.maven.org/maven2/com/contentsquare/android/sdk/maven-metadata.xml
• sdk-compose（Jetpack Compose を使用する場合のみ）：https://repo1.maven.org/maven2/com/contentsquare/android/sdk-compose/maven-metadata.xml

これらのファイルは Maven Central から直接提供されるものであり、信頼できる情報源です。 search.maven.org API は使用しないでください。インデックスの更新が遅れており、古いバージョンが頻繁に返されます。

各 maven-metadata.xml からバージョンを選ぶ方法：

1. <versioning><versions> 内のすべての <version> エントリーを読み取ります。
2. プレリリースを除外します。-SNAPSHOT、-alpha、-beta、-rc、-dev、-M を含むバージョンは破棄します（大文字と小文字は区別しません）。
3. 残りのバージョンをセマンティックバージョンの順序（メジャー、マイナー、パッチの順に数値で比較）で並べ替えます。
4. 最も高いバージョンを選びます。<latest> タグは参考として使用してもかまいませんが、必ずプレリリースでないことを確認してください。

バージョンの整合性に関するルール：

• sdk と sdk-compose は、必ず完全に同じバージョン文字列に固定してください。
• 各アーティファクトの最新安定版を個別に確認してから、両方のリストに存在する最も高いバージョンを使用してください。

// Module-level build.gradle.kts
dependencies {
    implementation("com.contentsquare.android:sdk:X.Y.Z") // resolved latest stable

    // Only if the app uses Jetpack Compose (MUST match sdk version exactly):
    implementation("com.contentsquare.android:sdk-compose:X.Y.Z")
}

プロジェクト要件

• minSdkVersion：21（Android 5.0 Lollipop）
• compileSdkVersion：34 以上
• Java：11（sourceCompatibility / targetCompatibility / jvmTarget = 11。これより低い Java バージョンでは bad class file エラーが発生します）。Java 17 以降も使用できます。
• Kotlin：1.8.22（SDK には stdlib が含まれています。競合する場合は org.jetbrains.kotlin:kotlin-stdlib-jdk8 を除外してください）
• Jetpack Compose：Compose Compiler 1.4.8（Compose BOM 2024.09.00 でテスト済み）。sdk-compose を使用する場合

AndroidManifest.xml の権限を手動で追加する必要はありません。SDK が必要な権限を宣言し、自動的にマージします。

クイックスタート

Experience Analytics の最小限の統合です。SDK がデータを収集するには、CSQ.start(...) と CSQ.optIn() の両方が必要です。optIn() を呼び出さない場合、ユーザーはデフォルトでオプトアウトされ、enabledForCollection は false のままです（logcat で確認できます）。必ず両方の呼び出しを記述してください。クイックスタートの統合では、同意フローに記述するべきものに見える場合でも、optIn() を省略しないでください。TODO: REVIEW BEFORE RELEASE コメントは、リリース前に実際の同意フローへ呼び出しを移動する必要があることをレビュアーに示すための取り決めです。

import android.app.Application
import com.contentsquare.CSQ

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        CSQ.start(this)
        // TODO: REVIEW BEFORE RELEASE — `optIn()` MUST be wired to your real
        // consent flow (CMP / consent dialog) and NOT called unconditionally
        // here.
        CSQ.optIn()
    }
}

AndroidManifest.xml に MyApplication を登録することも忘れないでください。

<application android:name=".MyApplication" ... >

画面のトラッキング（Android Views）：

import com.contentsquare.CSQ

class HomeActivity : AppCompatActivity() {
    override fun onResume() {
        super.onResume()
        CSQ.trackScreenview("HomeScreen")
    }
}

画面のトラッキング（Jetpack Compose）：

import com.contentsquare.CSQ
import com.contentsquare.api.compose.TriggeredOnResume

@Composable
fun HomeScreen() {
    TriggeredOnResume {
        CSQ.trackScreenview("HomeScreen")
    }
    // screen content
}

統合の確認

同じ実行中に以下のログが両方表示されれば、統合はエンドツーエンドで検証済みです。

1. SDK の起動（常に出力されます）：

   CSQ <version> for <Product Analytics|Experience Analytics> is attempting to start.
   

   および

   Contentsquare SDK <legacy-version> starting in app: <package>
   

2. データが収集され、永続化されていること — 以下のうち少なくとも 1 つ：

   Tracked pageview from android_view_autocapture.
   User.writeToDb: Attempting to insert user - envId: <ID>, userId: <ID>, ...
   writeToDb: Attempting to insert session - envId: <ID>, userId: <ID>, sessionId: <ID>
   All pending data has been uploaded.
   

   これらのいずれかが、optIn() が機能し、データが送信されていることの証明になります。

⚠️ enabledForCollectionを診断目的で使用しないでください

次の行は：

BatchUploaderOrchestrator: Condition not met - state.isFullyStopped: false  enabledForCollection is false.

SDK の通常の起動中に複数回出力されます。optIn()が正しく呼び出されている場合でも同様です。これは、オーケストレーターがメモリ内の状態の読み込み完了前に実行されるためです。これだけでは失敗を示すものではありません。 Starting service DXA／Starting service PAと交互に3、4回出力されるのは想定どおりです。

同じlogcatセッション内に「writeToDb」／「Tracked pageview」／「All pending data has been uploaded」のいずれかの行が一度も出現しない場合に限り、実際の問題を示します。このログを根拠に、インテグレーションからCSQ.optIn()を削除しないでください。

よくある失敗パターン

• ❌ 起動ログは出るが、writeToDb: Attempting to insert user／sessionの行が一度も出ない → CSQ.optIn()がないか、実行されていません。Application.onCreate()内でCSQ.start(...)の直後にCSQ.optIn()を追加してください（完了条件の項目3を参照）。
• ❌ CSQログがまったく出ない → Applicationサブクラスが、android:name=".MyApplication"を使ってAndroidManifest.xmlに登録されていません。
• ❌ mobile-production.content-square.net/android/config/v2/<package>.jsonで404が発生する → このapplicationId用のContentsquareプロジェクトがまだプロビジョニングされていません。インテグレーション初期段階では想定される状態です。顧客にプロジェクトの作成を依頼してください。トラッキングはローカルで引き続き動作し、イベントはSQLiteに保存され、プロジェクト作成後にアップロードされます。
• ❌ 起動中にonTrackingStarted: config, or environment null aborting.が一度出現する → 問題ありません。PAのみでアプリが起動された際に、EAの経路が出すメッセージです。何秒も続かない限り無視してください。

開発中に詳細ログを出力するには、start()の直後にデバッグログを有効にします：

import com.contentsquare.api.model.LogLevel
CSQ.debug.logLevel = LogLevel.DEBUG

SDK の起動 — 3つのオーバーロード

すべての起動方法はcom.contentsquare.CSQで公開されています。パッケージはcom.contentsquareであり、com.contentsquare.androidではありません。

1. Experience Analyticsのみ（デフォルト）

CSQ.start(context = this)

2. Product Analytics（任意でEA拡張を追加）— environmentId

import com.contentsquare.CSQ
import com.contentsquare.StartConfig
import com.contentsquare.api.model.AnalyticsOptions

CSQ.start(
    context = this,
    StartConfig.withEnvironmentId(
        id = "YOUR_ENVIRONMENT_ID",
        options = AnalyticsOptions(
            enableViewAutocapture = true
        )
    )
)

StartConfigは、com.contentsquareパッケージにあるトップレベルのシールドクラスです。AnalyticsOptions、Transaction、Currency、CustomVar、NetworkMetric、Metadata、Debug、LogLevelはすべてcom.contentsquare.api.modelにあります。

3. 統合CSQ — dataSourceId

CSQ.start(
    context = this,
    StartConfig.withDataSourceId(id = "YOUR_DATASOURCE_ID")
)

environmentIdとdataSourceIdは、app.contentsquare.comのContentsquareプロジェクト設定から取得します。ハードコードしないでください。BuildConfig、環境変数、または設定リソースから読み込んでください。

AnalyticsOptions（現在のオプション、v1.11.x）

オプション	型	デフォルト	用途
enableViewAutocapture	Boolean	false	UI操作とソースページビューを自動キャプチャします（Android Viewsのみ。Composeには対応していません）。
disablePageviewAutocapture	Boolean	false	自動キャプチャされるソースページビューを無効にします。
enablePushNotificationAutocapture	Boolean	false	通知上での操作を自動キャプチャします。
enablePushNotificationTitleAutocapture	Boolean	false	通知タイトルをキャプチャします（enablePushNotificationAutocapture = trueが必要です）。
enablePushNotificationBodyAutocapture	Boolean	false	通知本文をキャプチャします（enablePushNotificationAutocapture = trueが必要です）。
baseUri	URI	URI("https://mh.bf.contentsquare.net")	APIエンドポイントのベースURIです。
uploadInterval	Double（秒）	15.0	イベントバッチをアップロードする間隔です。
sessionReplayAutoStart	Boolean	true	Session Replayの自動開始を無効にするにはfalseに設定します。CSQ.startSessionReplay()／CSQ.stopSessionReplay()で手動制御できます。

StartConfig.dxa()も、任意のAnalyticsOptionsパラメーターを受け取ります（例：EAのみのモードでSession Replayの自動開始を無効にする場合）。

古いドキュメントと以前のCSQ.configureProductAnalytics(...)メソッドは非推奨です。新しいインテグレーションでは、必ずCSQ.start(context, StartConfig.…)を使用してください。

Heap の自動キャプチャ（PA／Unified モードのみ）

お客様が CSQ.start(context) だけで CSQ を開始した場合（EA のみモード）は、このセクション全体をスキップしてください。 io.heap.gradle プラグインと ComposeAutocaptureSDK は、StartConfig.withEnvironmentId(...)（Product Analytics）または StartConfig.withDataSourceId(...)（Unified）で CSQ を開始した場合にのみ適用されます。EA のみのインテグレーションでは、明示的な CSQ.trackScreenview(...) API を通じてページビューを取得できるため、これらは必要ありません。

お客様が environmentId（PA）または dataSourceId（Unified）を指定した場合、Heap 形式の自動キャプチャを有効にしています。操作（ボタンのタップ、画面表示など）を実際に自動取得するには、アプリに Heap Gradle Plugin によるバイトコード計測を追加する必要があります。

View の自動キャプチャ（Android Views）

1. モジュールの build.gradle.kts にプラグインを適用します（settings やルートではありません）。

   plugins {
       id("com.android.application")
       kotlin("android")
       id("io.heap.gradle") version "1.1.1" // latest stable
   }
   

   利用可能な最新の安定版はこちらです：https://repo1.maven.org/maven2/io/heap/gradle/io.heap.gradle.gradle.plugin/maven-metadata.xml。sdk／sdk-compose と同じ選定ルールを適用してください。

2. AnalyticsOptions を使って View の自動キャプチャを有効にします（内部で ViewAutocaptureSDK.register() が呼び出されます。手動では呼び出さないでください）。

   CSQ.start(
       context = this,
       StartConfig.withEnvironmentId(
           id = BuildConfig.CSQ_ENVIRONMENT_ID,
           options = AnalyticsOptions(enableViewAutocapture = true)
       )
   )
   

確認方法：logcat に Source android_view_autocapture successfully registered. と表示され、（タップまたは画面変更後に）Tracked pageview from android_view_autocapture. と表示されます。

Compose の自動キャプチャ

enableViewAutocapture = true は Jetpack Compose を対象にしません。ドキュメント文字列にも 「Android View システムのみ。Compose はサポートしていません。」 と明記されています。Compose の自動キャプチャには、以下の 3 つすべてが必要です。

1. io.heap.gradle プラグインが適用されている（上記の View の自動キャプチャと同じ）。

2. implementation("com.contentsquare.android:sdk-compose:<version>") を通じて sdk-compose アーティファクトがすでに追加されている（推移的に io.heap.autocapture:heap-autocapture-compose も追加されます）。

3. CSQ.start(...) の後に手動で登録する。

   import io.heap.autocapture.compose.ComposeAutocaptureSDK
   
   override fun onCreate() {
       super.onCreate()
       CSQ.start(this, StartConfig.withEnvironmentId(BuildConfig.CSQ_ENVIRONMENT_ID))
       ComposeAutocaptureSDK.register()  // Compose autocapture is NOT enabled by AnalyticsOptions
       CSQ.optIn() // TODO: REVIEW BEFORE RELEASE — see Privacy/Consent
   }
   

   インポートに注意してください：io.heap.autocapture.compose.ComposeAutocaptureSDK（これはバンドルされた Heap autocapture-compose モジュール内にあり、com.contentsquare.* 内にはありません）。

確認方法：logcat に Source android_compose_autocapture successfully registered. と表示されます。(HeapInstrumentation) semantics: capture is disabled; using stock Modifier.semantics という行は正常です。semantics のキャプチャは ComposeAutocaptureSDK.register(enableSemanticsCapture = true) でオプトインするもので、ほとんどのアプリではデフォルトのままで問題ありません。

自動キャプチャと併用できる手動の画面表示記録

自動キャプチャが有効でも、CSQ.trackScreenview("Conversation") や Compose の TriggeredOnResume { … } を使って、名前付きの画面表示を記録できます（多くの場合、記録することを推奨します）。手動で指定した名前は、自動的に導出されるクラス名やルート名よりも、Heap UI で意味のわかりやすいラベルになります。

プライバシー／同意

SDK では、すべてのユーザーがデフォルトでオプトアウトしているものとして扱われます。トラッキングは optIn() が呼び出された後にのみ開始されます。

// In your consent UI (button click, dialog confirmation, etc.)
CSQ.optIn()

// To revoke consent
CSQ.optOut()

以前の CSQ.optIn(context: Context) オーバーロードも存在しますが、非推奨です。必ず引数なしの CSQ.optIn() を使用してください。

ルール：

• optIn() は start() の後に呼び出してください。
• Application.onCreate() で optIn() を自動的に呼び出さないでください。明示的なユーザー同意を待ってください。
• optOut() はユーザー ID を削除し、再度 optIn() が呼び出されるまで、すべてのトラッキングを停止します。
• データ主体からの請求に対応するために Contentsquare ユーザー ID を取得するには、CSQ.metadata.userId を使用します。

一時停止／再開

決済フローなど、機密性の高い画面ではトラッキングを一時停止します。

CSQ.pauseTracking()
// ... user is on the sensitive screen ...
CSQ.resumeTracking()

API の概要

すべてのメソッドは com.contentsquare.CSQ オブジェクトにあります。

ライフサイクル

• CSQ.start(context) — SDK を開始します（EA のみ）。
• CSQ.start(context, StartConfig.withEnvironmentId(id, options)) — PA（EA は任意）。
• CSQ.start(context, StartConfig.withDataSourceId(id)) — Unified CSQ。
• CSQ.stop() — SDK を停止します。
• CSQ.pauseTracking()／CSQ.resumeTracking() — データ収集を一時停止／再開します。

プライバシー

• CSQ.optIn() — ユーザーをトラッキングの対象にします。start() の後に呼び出す必要があります。
• CSQ.optOut() — トラッキングを停止し、ユーザーデータを消去します。

ID

• CSQ.identify(identity: String) — （PA）ID を割り当てます。最大 255 文字です。新しいユーザー ID とセッションが開始されます。
• CSQ.resetIdentity() — （PA）ID を消去し、新しいセッションを開始します。
• CSQ.sendUserIdentifier(identifier: String) — （EA）ハッシュ化されたユーザー識別子を送信します。最大 100 文字です。フォアグラウンドに入るたびに呼び出すことを推奨します（ProcessLifecycleOwner を使用）。

画面トラッキング

• CSQ.trackScreenview(name: String, customVars: List<CustomVar> = emptyList()) — 画面表示をトラッキングします。
• CustomVar(index: Int /* 0..20 */, name: String /* ≤ 512 chars */, value: String /* ≤ 255 chars */)
• TriggeredOnResume { ... }（コンポーザブル、com.contentsquare.api.compose 内）— Compose で trackScreenview の呼び出しをラップし、画面が表示されるたびに 1 回だけ実行します。

画面名：アプリごとに 100 個未満の重複しない名前を使用してください。PII（メールアドレス、氏名、アカウント ID など）は絶対に含めないでください。

トランザクション（EA）

import com.contentsquare.api.model.Transaction
import com.contentsquare.api.model.Currency

val transaction = Transaction(value = 430.99f, currency = Currency.EUR, id = "order_123")
CSQ.trackTransaction(transaction)

シグネチャ：Transaction(value: Float, currency: Currency, id: String? = null)。

⚠️ 各トランザクションは 1 回だけ送信してください。 よくある間違いとして、確認画面の onResume() から呼び出すと、ユーザーがアプリを再びフォアグラウンドにするたびに送信されてしまいます。

Currency は ISO 4217 に準拠した列挙型です。ヘルパー：Currency.fromString("USD")、Currency.fromInteger(840)、Currency.USD.stringCode。

カスタムイベントとプロパティ

• CSQ.trackEvent(event: String, properties: Map<String, Any> = mapOf()) — （PA）名前付きイベントをトラッキングします。
• CSQ.addUserProperties(properties: Map<String, Any>) — （PA）ユーザーレベルのプロパティを設定します。
• CSQ.addEventProperties(properties: Map<String, Any>) — （PA）以降のすべてのイベントに追加するプロパティを設定します。
• CSQ.removeEventProperty(key: String) — （PA）イベント全体に適用されるプロパティを 1 つ削除します。
• CSQ.clearEventProperties() — （PA）イベント全体に適用されるすべてのプロパティを削除します。
• CSQ.addDynamicVar(key: String, value: String) / CSQ.addDynamicVar(key: String, value: Long) — （EA）セッションレベルの変数を追加します。キーは最大 512 文字で、画面表示ごとに異なるキーは最大 40 個です。

プロパティ値には、String、Number、Boolean、または Property インターフェースを実装するオブジェクトを指定できます。

セッションリプレイのマスキング

デフォルトの動作：すべてマスキングされます。表示する要素は明示的にマスキングを解除してください。

ビュー：

• CSQ.setDefaultMasking(masked: Boolean) — グローバルなデフォルト設定です。EditText／Compose の TextField には影響しません。
• CSQ.mask(view: View)／CSQ.unmask(view: View) — インスタンスごとの設定です。
• CSQ.mask(type: Class<*>)／CSQ.unmask(type: Class<*>) — 型ごとの設定です。（EA）
• CSQ.maskTexts(mask: Boolean) — テキストのマスキングを切り替えるグローバル設定です。
• view.csqMaskContents(enable: Boolean) — View の Kotlin 拡張関数です。
• CSQ.ignoreInteractions(view: View)／view.csqIgnoreInteractions() — ビューのジェスチャートラッキングを停止します。

Compose：

• CsqMask(enable: Boolean) { content } — コンポーザブルのサブツリーをマスキングします（セッションリプレイ＋アナリティクス）。
• CsqIgnoreInteraction(ignore: Boolean) { content } — サブツリー内のインタラクションを無視します。
• CsqTag(CsqTag.ModalBottomSheetLayout) { content } — 特別な処理が必要なコンポーザブルにタグを付けます（ModalBottomSheetLayout のヒートマップ／ゾーニングをサポート）。

ダイアログ（ビュー） — com.contentsquare.api.sessionreplay の拡張関数：

• AlertDialog.csqMask()、csqMaskTitle()、csqMaskMessage()、csqMaskPositiveButton()、csqMaskNegativeButton()（および対応する csqUnmask… 関数）。
• DatePickerDialog.csqMask()、csqMaskHeader()、csqMaskCalendar()、csqMaskButtonPanel()（および対応する csqUnmask… 関数）。
• TimePickerDialog.csqMask()、csqMaskHeader()、csqMaskRadialPicker()、csqMaskInputMode()、csqMaskButtonPanel()（および対応する csqUnmask… 関数）。
• メインスレッドで dialog.show() の直後に呼び出してください。

メニュー（ビュー）：

• CSQ.maskMenuItem(itemId)／CSQ.unmaskMenuItem(itemId) — メニュー項目を個別にマスキング／マスキング解除します。

マスキングを呼び出す場所：

• Activity：onCreate() 内。
• Fragment：onViewCreated() 内。
• 必ず最初の描画前に、UI スレッドで呼び出してください。

注意すべき制限事項：

• インスタンスまたは型ごとのマスキングではアニメーションはサポートされません。代わりに親または画面全体をマスキングしてください。
• Compose：型ごとのマスキングは利用できません。代わりに親コンポーザブルを CsqMask で囲んでください。
• SurfaceView と MapView のコンテンツは部分的にマスキングできません。

セッションリプレイの制御

AnalyticsOptions.sessionReplayAutoStart = false の場合、記録を手動で制御します。

CSQ.startSessionReplay()
// ...
CSQ.stopSessionReplay()

イベントトリガー型リプレイ（ETR、オプションのアドオン）

CSQ.triggerReplayForCurrentSession(name = "checkout_funnel")
CSQ.triggerReplayForCurrentScreen(name = "payment_failure")

WebView トラッキング

CSQ.registerWebView(webView)
// later:
CSQ.unregisterWebView(webView)

内部で読み込まれるウェブページにも Contentsquare WebView Tracking Tag が必要です。WebView のドキュメントを参照してください。

アンケート（EA Voice of Customer）

CSQ.triggerSurvey("purchase-complete")

エラートラッキング（EA）

import com.contentsquare.api.contract.CsqOkHttpInterceptor

val client = OkHttpClient.Builder()
    .addInterceptor(CsqOkHttpInterceptor())
    .build()

// Mask sensitive URL paths
CSQ.setUrlMaskingPatterns(listOf("/users/[0-9]+", "/orders/[A-Z0-9-]+"))

// Manual network metric tracking (statusCode required for proper error reporting)
import com.contentsquare.api.model.NetworkMetric
import com.contentsquare.api.model.HttpMethod

val metric = NetworkMetric("http://www.example.com", HttpMethod.GET)
// ... perform request ...
metric.statusCode = 500
metric.responseBody = body
CSQ.trackNetworkMetric(metric)

// Manual gesture tracking when autocapture is not enough
override fun dispatchTouchEvent(motionEvent: MotionEvent): Boolean {
    CSQ.trackMotionEvent(motionEvent)
    return super.dispatchTouchEvent(motionEvent)
}

CsqOkHttpInterceptor を使用するには、クラスパスに OkHttp 4.x が必要です（SDK では compileOnly として宣言されています）。

ビュートラッキング

• CSQ.excludeFromExposureMetric(view: View) — ScrollView または RecyclerView を Exposure Metrics の対象から除外します。（EA）

デバッグ、ログ記録、メタデータ

import com.contentsquare.api.model.LogLevel

CSQ.debug.logLevel = LogLevel.DEBUG // NONE, ERROR, WARN, INFO (default), DEBUG, TRACE
CSQ.debug.logChannel = customLogChannel // Implement com.contentsquare.api.contract.LogChannel to route to Timber, etc.

val userId       = CSQ.metadata.userId
val sessionId    = CSQ.metadata.sessionId
val projectId    = CSQ.metadata.projectId
val envId        = CSQ.metadata.environmentId
val replayUrl    = CSQ.metadata.sessionReplayUrl
val identity     = CSQ.metadata.identity

CSQ.metadata.onChanged = OnMetadataChanged { metadata ->
    // Forward replay URL to your CRM / crash reporter
}
// Unregister:
CSQ.metadata.onChanged = null

よくあるパターン

1. アプリケーションの初期化（EA のみ）

import com.contentsquare.api.model.LogLevel

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        CSQ.start(this)
        if (BuildConfig.DEBUG) CSQ.debug.logLevel = LogLevel.DEBUG
        // TODO: REVIEW BEFORE RELEASE — wire `optIn()` to your real consent flow.
        CSQ.optIn()
    }
}

2. アプリケーションの初期化（Product Analytics）

import com.contentsquare.CSQ
import com.contentsquare.StartConfig
import com.contentsquare.api.model.AnalyticsOptions

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        CSQ.start(
            context = this,
            StartConfig.withEnvironmentId(
                id = BuildConfig.CSQ_ENV_ID,
                options = AnalyticsOptions(enableViewAutocapture = true)
            )
        )
    }
}

3. 同意フロー

fun handleConsent(userAccepted: Boolean) {
    if (userAccepted) CSQ.optIn() else CSQ.optOut()
}

4. 購入をトラッキングする

CSQ.trackTransaction(
    Transaction(value = 49.99f, currency = Currency.EUR, id = "txn_abc")
)

5. プロパティ付きカスタムイベント（PA）

CSQ.trackEvent(
    event = "add_to_cart",
    properties = mapOf(
        "product_id" to "sku_123",
        "quantity"   to 2,
        "is_promo"   to true
    )
)

6. OkHttp エラートラッキング

import com.contentsquare.api.contract.CsqOkHttpInterceptor

val client = OkHttpClient.Builder()
    .addInterceptor(CsqOkHttpInterceptor())
    .build()

7. 選択的なマスキングを行う Compose 画面

@Composable
fun ProductDetailScreen(product: Product) {
    TriggeredOnResume { CSQ.trackScreenview("ProductDetail") }
    Column {
        Text(text = product.name) // masked by default
        CsqMask(enable = false) {
            Text(text = product.publicDescription) // explicitly visible
        }
    }
}

8. フォアグラウンドに入るたびにハッシュ化したユーザー識別子を送信する（EA）

ProcessLifecycleOwner.get().lifecycle.addObserver(object : DefaultLifecycleObserver {
    override fun onStart(owner: LifecycleOwner) {
        currentUser?.email?.let { CSQ.sendUserIdentifier(it) }
    }
})

避けるべきアンチパターン

• ❌ CSQ.trackScreenview("[email protected]") → 画面名に個人情報が含まれています。✅ "ProfileScreen" を使用してください。
• ❌ ソースコードに environmentId ／ dataSourceId をハードコードする。✅ BuildConfig またはリソースを使用してください。
• ❌ 本番環境で CSQ.optIn() を無条件に Application.onCreate() に含めてリリースする。✅ リリース前に、実際の同意フロー（CMP ／同意ダイアログ）に接続してください。初期統合と QA の間は、SDK をエンドツーエンドで検証できるよう、TODO: REVIEW BEFORE RELEASE コメントで保護したうえで onCreate() に残しても問題ありません。
• ❌ 確認画面の onResume() から同じ Transaction を送信する。✅ 注文が成功した後に一度だけ送信してください。
• ❌ sdk と sdk-compose で異なるバージョンを使用する。✅ 両方をまったく同じバージョンに固定してください。
• ❌ 非推奨の CSQ.configureProductAnalytics(...) を使用する。✅ CSQ.start(context, StartConfig.…) を使用してください。
• ❌ @Composable 内で CSQ.trackScreenview を直接呼び出す（再コンポーズのたびに実行されます）。✅ TriggeredOnResume { … } でラップしてください。
• ❌ CSQ.start() の前に CSQ.optIn() を呼び出す。✅ 先に start を呼び出し、その後に optIn を呼び出してください。

旧バージョンからの移行

ホストアプリで CSQ SDK（com.contentsquare.android:sdk）の旧バージョンをすでに宣言している場合は、ほかの作業に着手する前に、該当する移行ガイドを確認してください。

現在のバージョン	対象バージョン	ガイド
1.0.x ～ 1.5.x	1.11.x	references/migration-1.5-to-1.11.md

Classic Contentsquare SDK（com.contentsquare.android:library）または Heap Core + Contentsquare の組み合わせから移行する場合は、Contentsquare のドキュメントから専用の upgrade-from-cs-sdk ／ upgrade-from-heap-and-cs-sdk ページを取得してください（下記の References セクションを参照）。これらの移行方法は、このスキルでは対象としていません。

参考資料

Contentsquare の公式ドキュメントでは、すべてのページの Markdown 版を公開しています。最新情報を取得するには、必要に応じて取得してください。このスキルにキャッシュされたスナップショットより、常にこちらを優先してください。

• ドキュメントインデックス（LLM 向け）： https://docs.contentsquare.com/llms.txt
• はじめに（Experience Analytics）： https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/index.md
• はじめに（Product Analytics）： https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/index.md
• EA SDK API リファレンス： https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/command-reference/index.md
• PA SDK API リファレンス： https://docs.contentsquare.com/en/csq-sdk-android/product-analytics/command-reference/index.md
• 互換性（minSdk、Java/Kotlin/Compose のバージョン）： https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/compatibility/index.md
• プライバシーと同意： https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/privacy/index.md
• Session Replay（マスキングの詳細）： https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/session-replay/index.md
• 画面のトラッキング： https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-screens/index.md
• トランザクションのトラッキング： https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-transactions/index.md
• トラブルシューティング： https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/troubleshooting/index.md
• 変更履歴： https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/changelog/index.md
• Android サンプルアプリ（GitHub）： https://github.com/ContentSquare/contentsquare-android-sample

各参考資料を読み込むタイミング：

• 正確なメソッドシグネチャやパラメーター一覧が必要な場合 → API リファレンスを取得してください。
• マスキングの実装やデバッグを行う場合 → Session Replay ページを取得してください。
• 互換性やバージョンの競合（Kotlin、Compose、依存関係）について確認する場合 → Compatibility ページを取得してください。
• Classic Contentsquare SDK または Heap から移行する場合 → llms.txt から該当する upgrade-from-… ページを取得してください。

選択した参考資料のローカルミラーも、このスキルの隣にあります。

• references/api-reference.md
• references/session-replay.md
• references/migration-1.5-to-1.11.md