mcpField
C
contentsquare-flutter-sdk

contentsquare-flutter-sdk

github.com/contentsquare開発239 回インストール1 週間前に更新
リポジトリ

contentsquare-flutter-sdk について

クライアントアプリへの Contentsquare Flutter SDK の導入やアップグレードを支援するスキルです。プロジェクトのヘルスチェック、SDK 設定、分析計測、移行手順を扱います。

主な機能

  1. 01プロジェクト設定のヘルスチェック
  2. 02Flutter SDK の導入と設定
  3. 03画面と WebView の計測ガイド
  4. 04分析とリプレイ API のガイド
  5. 05SDK バージョン移行のガイド

活用シーン

  1. 01Flutter アプリへの Contentsquare 導入
  2. 02既存 Contentsquare SDK のアップグレード
  3. 03プロジェクト設定と計測の問題調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/contentsquare/agents --skill contentsquare-flutter-sdk

インストール後、Claude Code で/contentsquare-flutter-sdkを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
api-reference.md
common-patterns.md
ios-in-app-features.md
migration.md
screen-tracking.md
session-replay.md

詳細

Contentsquare Flutter SDK の統合

このスキルは、AI エージェントがクライアントアプリケーションに Contentsquare Flutter SDK を統合またはアップグレードする際に役立ちます。

必ず最初に行う手順 -- Contentsquare プロジェクトのヘルスチェック

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

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

    "始める前に、Contentsquare プロジェクトの簡単なヘルスチェックを実行します。データソース ID をお尋ねするか、お持ちでない場合はアプリのバンドル ID を確認し、Contentsquare のヘルスチェックエンドポイントを呼び出して、現在のプロジェクト設定をお見せします。その後、作業を続けます。"

  2. まずユーザーに Contentsquare のデータソース ID を尋ねます。 たとえば、次のように尋ねます。「Contentsquare のデータソース ID はありますか？ Android 用と iOS 用など、1つまたは複数ある場合があります。お持ちでしたら、それぞれがどのプラットフォーム用か教えてください。」 ユーザーが提示した ID のみを使用してください。決して ID を捏造しないでください。

    • ユーザーが1つ以上のデータソース ID を提示した場合 → データソース ID のみで確認します（v3）。手順3は省略します。
    • ユーザーが環境 ID のみを持っている場合 → バンドル ID のみで確認します（v2）。環境 ID はデータソース ID ではなく、v3 の方法では使えません。
    • ユーザーが ID を持っていない、分からない、または質問をスキップした場合 → バンドル ID のみで確認します（v2）。

  3. バンドル ID を特定します（データソース ID がない場合のみ）。Flutter アプリにはバンドル ID が2つあり、文字列が異なることもよくあります。 それぞれを個別に特定してください。同じものだと決めつけないでください。

    プラットフォーム確認する場所
    Androidandroid/app/build.gradle(.kts) の applicationId（見つからない場合は namespace、または AndroidManifest.xml の package を確認）
    iOSios/Runner.xcodeproj/project.pbxproj の PRODUCT_BUNDLE_IDENTIFIER（または ios/Runner/Info.plist の CFBundleIdentifier）。$(...) 変数があれば解決します。

  4. エンドポイントを呼び出します。使用するバージョンは1つのみで、両方を使用しないでください。 プラットフォームの値は文字どおり ios または android でなければなりません。Flutter というプラットフォームの値はありません。決して送信しないでください。

    データソース ID を使用する場合（v3）、ID ごとに1回：

    curl -s "https://mobile-production.content-square.net/healthcheck/android/config/v3/<dataSourceId>.json"
curl -s "https://mobile-production.content-square.net/healthcheck/ios/config/v3/<dataSourceId>.json"

    各 ID を、ユーザーが指定したプラットフォームで照会します。プラットフォームが不明な場合は、プロジェクトに存在する各プラットフォームで照会します。一方のプラットフォームで 200 以外の応答があっても、そのデータソースがそのプラットフォーム用に設定されていないことを意味するだけです。

    いずれのプラットフォームで照会しても ID に対して 200 が返されない場合は、その旨をユーザーに伝えてください。環境 ID または入力ミスの可能性があります。コード内でデータソース ID を探してもよいか確認してください。これは StartConfig.withDatasourceId(id: ...) に渡される ID です。定数や設定ファイルから取得している場合は、実際の値までたどってください。ユーザーが同意し、別の ID が見つかった場合は、その ID で v3 の確認を1回実行します。ユーザーが同意しない場合、またはコード内に ID がない場合は、ID なしで続行します。

    データソース ID を使用しない場合（v2）、存在するプラットフォームごとに1回：

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

    プロジェクトに存在するプラットフォームが1つだけの場合は、そのプラットフォームのみを照会します。バンドル ID のいずれかを特定できない場合は、推測せず、どのプラットフォームを確認すればよいかユーザーに尋ねてください。

  5. 各呼び出しで 200 が返された場合は、次の値を簡潔にまとめて報告します。

    レポートJSON パス
    プロジェクト IDcs_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 を含みます

    v3 の呼び出しでは、環境 ID（environment_id）も報告してください。

    Android と iOS で異なる Contentsquare プロジェクトに対応付けられている場合があります。レスポンスが異なる場合は、その旨を明記してください。

  6. その後、続けてユーザーの実際のリクエストに対応してください。

失敗時の処理。 403 Invalid health-check path は URL の形式が間違っていることを意味します。ios／android セグメント、v2／v3 セグメント、ID を再確認し、パス構造は変更しないでください。上流からプロキシされたステータスが 200 以外の場合、そのデータソース ID またはバンドル ID には該当プラットフォームの Contentsquare 設定がありません。その旨を伝えたうえで、処理を続けてください。別のバージョンで再試行してはいけません（再試行できるのは手順 4 のコード検索のみです）。このヘルスチェックは情報提供のみを目的としており、ユーザーのタスクを妨げてはいけません。

インストール

dependencies:
  contentsquare: ^4.5.1

次に、flutter pub get を実行します。

すでに ^4.1.x をお使いですか？ このリリースには、AnalyticsOptions／ProductAnalyticsOptions の破壊的変更（いくつかのフィールドの削除）と、configureProductAnalytics(...) の非推奨化が含まれています。バージョンを上げる前に、4.1.x から 4.5.1 への移行のセクションをお読みください。

すでに ^3.x をお使いですか？ v4 リリースには、API 名の変更、ContentsquareRoot の削除、ネイティブコードのクリーンアップなどの破壊的変更が含まれています。アップグレードする前に、旧 Contentsquare API から CSQ への移行（v3.x → v4.x）のセクションをお読みください。

クイックスタート

import 'package:contentsquare/csq.dart';
import 'dart:async';
import 'package:flutter/material.dart';

void main() async {
  runZonedGuarded(() async {
    WidgetsFlutterBinding.ensureInitialized();

    FlutterError.onError = (details) {
      CSQ().collectFlutterError(details: details);
    };

    await CSQ().start();
    await CSQ().optIn(); // TODO: customer to manage consent — call only after user accepts
    runApp(const MyApp());
  }, (error, stack) => CSQ().collectError(error: error, stackTrace: stack));
}

アプリのアーキテクチャ上必要な場合を除き、runZonedGuarded の使用は避けてください。これを使わない初期化方法については、references/common-patterns.mdをご覧ください。

画面をトラッキングすることは非常に重要です。そうしないと、セッションリプレイが機能しません。trackScreenview() で画面を手動でトラッキングするか、自動トラッキングに推奨される CSQNavigatorObserver を使用できます。 画面の自動トラッキングを追加します。

MaterialApp(
  navigatorObservers: [CSQNavigatorObserver()],
);

重要： iOS アプリ内機能に必要な iOS の設定を追加してください。

MVP をラップする前に、アプリに WebView がある場合は、必ず対応してください。WebView は自動的にトラッキングされないため、すべての WebView をラップする必要があります。詳細については、以下の WebView のセクションをご確認ください。

API の概要

必ず package:contentsquare/csq.dart の CSQ を使用してください。Contentsquare クラスは非推奨です。

ライフサイクル
メソッド目的
start({StartConfig, CSQMaskingConfig?})SDK を起動します。他の API を呼び出す前に必ず実行してください。
stop()SDK を完全にシャットダウンします。
pauseTracking()データ収集を一時停止します（機密性の高い画面で使用します）。明示的に指示された場合を除き、使用しないでください。
resumeTracking()pauseTracking() の後に再開します。
StartConfig のバリエーション
ファクトリーユースケースオンボーディングの優先順位
StartConfig.withDatasourceId(id:, options:)データソース ID を使用する CSQ新規クライアントの第一候補 -- まずこれについて確認してください
StartConfig.withEnvironmentId(id:, options:)環境 ID を使用する Product Analyticsデータソース ID がない場合の第二候補
StartConfig.dxa({options})Digital Experience Analytics のみ（デフォルト）。options は AnalyticsOptions です -- 4.2.0 で追加フォールバックのみ -- どちらの ID もない場合、または DXA のみが明示的に要求された場合

3 つのバリエーションすべてで、同じ AnalyticsOptions オブジェクトを受け取ります（下記の AnalyticsOptions セクションを参照）。

推奨されるオンボーディングの流れ：

  1. ユーザーに「Contentsquare のデータソース ID をお持ちですか？」と尋ねます（ヘルスチェック時にすでに回答済みの場合は、この質問を省略します）。「はい」の場合は、StartConfig.withDatasourceId(id: ...) を使用します。
  2. ない場合は、「環境 ID をお持ちですか？」と尋ねます。「はい」の場合は、StartConfig.withEnvironmentId(id: ...) を使用します。
  3. どちらもない場合（またはユーザーが DXA のみを明示的に希望する場合）に限り、StartConfig.dxa() にフォールバックします。
  4. 「Product Analytics / Unified CSQ 環境は EU でホストされていますか？」と尋ねます。「はい」の場合は、AnalyticsOptions に baseUrl: Uri.parse('https://mh.ba.contentsquare.net') を設定します。デフォルトのエンドポイントは US です。この設定を上書きしないと、EU 環境はデータを受信できません。

ID をでっち上げないでください。DXA を暗黙的にデフォルトにしないでください。US でホストされていると決めつけず、必ず確認してください。

プライバシー
メソッド目的
optIn()デバイスをトラッキングの対象にします。すぐに開始されます。
optOut()オプトアウトします。optIn() が呼び出されるか、アプリを再インストールするまで停止します。
ID
メソッドコンテキスト目的
identify(userIdentifier:)Product Analyticsユーザー ID を設定します。異なる ID を設定すると、新しいセッションが開始されます。
resetIdentity()Product AnalyticsID をクリアします。新しいセッションが開始されます。
sendUserIdentifier(userIdentifier:)DXAハッシュ化されたユーザー ID を送信します。最大 100 文字です。
画面トラッキング
メソッド目的
trackScreenview(screenName:, customVars:)画面表示を、任意のカスタム変数とともにトラッキングします。

CustomVar(index:, name:, value:) -- index（int）、name（String）、value（String）。

トランザクション
await CSQ().trackTransaction(
  Transaction(price: 29.99, currency: Currency.USD, id: 'order_123'),
);

Currency は ISO 4217 の列挙型です（例：Currency.USD、Currency.EUR）。

カスタムイベントとプロパティ
メソッド目的
trackEvent(eventName:, properties:)名前付きイベントを、任意のプロパティとともにトラッキングします。
addDynamicVar(DynamicVar)セッションレベルの動的変数を追加します。
addUserProperties(properties:)ユーザーレベルのプロパティを設定します。
addEventProperties(properties:)今後のすべてのイベントにプロパティを設定します。
removeEventProperty(name:)イベントプロパティを1つ削除します。
clearEventProperties()すべてのイベントプロパティを削除します。

プロパティの値は String、num、または bool である必要があります。それ以外の型は無視されます。

DynamicVar ファクトリー：DynamicVar.fromString(key:, value:) および DynamicVar.fromInt(key:, value:)。

セッションリプレイ
メソッド目的
triggerReplayForCurrentSession(name:)セッションをリプレイキャプチャ対象としてマークします（セグメント化／フィルタリング用）。
triggerReplayForCurrentScreen(name:)現在の画面をリプレイキャプチャ対象としてマークします。
startSessionReplay() (new in 4.2.0)セッションリプレイをオンデマンドで開始します。sessionReplayAutoStart: false を start() に渡した場合に使用します。1回限り -- 再起動用の API ではありません。
stopSessionReplay() (new in 4.2.0)SDK を停止せずにセッションリプレイをオンデマンドで停止します。終了操作 -- 同じ SDK のライフタイム内では、その後 SR を再開できません。

オンデマンドのセッションリプレイ -- SDK の起動時に自動開始を無効にし、手動で制御します。

await CSQ().start(
  startConfig: StartConfig.dxa(
    options: const AnalyticsOptions(sessionReplayAutoStart: false),
  ),
);
// later, when you want SR to start (e.g., entering a checkout flow):
await CSQ().startSessionReplay();
// and to stop it (final -- no restart afterwards):
await CSQ().stopSessionReplay();

startSessionReplay / stopSessionReplay は開始と停止のみで、一時停止／再開ではありません。stopSessionReplay() の後、次の SDK ライフタイムまで SR はオフのままです。

セッションメタデータ（リプレイリンクの取得）

リプレイ URL を含むセッション情報にアクセスします。

// Get current session replay URL (returns Uri?)
final replayUrl = CSQ().metadata.sessionReplayUrl;

// Listen for metadata changes
final subscription = CSQ().metadata.onChange((metadata) {
  print('Session Replay URL: ${metadata.sessionReplayUrl}');
});
subscription.cancel(); // Stop listening when done

Metadata のフィールド：projectId、environmentId、userId、identity、sessionId、sessionReplayUrl（Uri?）。

エラー報告
メソッド目的
collectFlutterError(details:, presentErrorDetails:)Flutter フレームワークのエラーを報告します。
collectError(error:, stackTrace:)捕捉したエラーを報告します。
setURLMaskingPatterns(patterns:)エラートラッキングで機密性の高い URL パスをマスクします。メールアドレスは自動的にマスクされます。

HTTP リクエストエラーを自動的にトラッキングするには、アプリの起動時に CSQHttpOverrides をグローバル HTTP オーバーライドとしてインストールしてください。詳しくは references/api-reference.md を参照してください。

Debug and Metadata
APIPurpose
debug.setLogLevel(LogLevel)Set log level (info, verbose, etc.)
metadataAccess session metadata. metadata.onChange(handler) to listen.
AnalyticsOptions（すべての StartConfig バリアントで共通）

すべてのフィールドは null 許容です（null = ネイティブのデフォルト動作）。

フィールド型プラットフォーム用途
enableInteractionsAutocapturebool?両方Flutter のインタラクション自動キャプチャ（PA）を有効にします
disablePageviewAutocapturebool?両方ネイティブのページビュー自動キャプチャを無効にします
enablePushNotificationAutocapturebool?両方プッシュ通知イベントをキャプチャします
enablePushNotificationTitleAutocapturebool?両方プッシュ通知のタイトルをキャプチャします
enablePushNotificationBodyAutocapturebool?両方プッシュ通知の本文をキャプチャします
baseUrlUri?両方カスタム API エンドポイントです。EU ホストの Product Analytics 環境では必須です：Uri.parse('https://mh.ba.contentsquare.net') を設定してください。オンプレミス／カスタムエンドポイントにも使用します。
uploadIntervalDuration?両方イベントをアップロードする間隔
sessionReplayAutoStartbool?両方false の場合、SDK の起動時に SR は開始されません。代わりに startSessionReplay() を使用してください
disablePageviewTitleAutocapturebool?iOS のみiOS のページタイトルの自動キャプチャを無効にします
disableInteractionAutocapturebool?iOS のみネイティブの iOS インタラクション自動キャプチャを無効にします

4.2.0 で削除（破壊的変更）：captureVendorId、captureAdvertiserId、clearEventPropertiesOnNewUser、resumePreviousSession、disableScreenviewForwardToDXA、disableScreenviewForwardToPA、messageBatchByteLimit、messageBatchMessageLimit、pruningLookBackWindow、maximumDatabaseSize、maximumBatchCountPerUpload。置き換えについては references/migration.md を参照してください。

ProductAnalyticsOptions は現在、AnalyticsOptions の typedef エイリアスです（後方互換性のために維持されています）。新しいコードでは AnalyticsOptions を使用してください。

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

グローバルマスキング（開始時）
await CSQ().start(
  maskingConfig: const CSQMaskingConfig(
    maskTexts: true,
    maskTextFields: true,
    maskImages: false,
  ),
);
スコープ付きマスキング（ウィジェットサブツリーごと）
CSQMask(
  config: const CSQMaskingConfig(maskTexts: true, maskInteractions: true),
  child: Text('Sensitive content'),
)
CSQMaskingConfig のフィールド
フィールドマスク対象
maskTextsText、RichText
maskTextFieldsTextField、TextFormField
maskImagesImage ウィジェット
maskSvgImagesSVG で描画される画像
maskChartsfl_chart ウィジェット
maskCustomPaints開発者が作成した CustomPaint ウィジェット
maskInteractionsユーザー操作（Product Analytics のみ）

便利なメソッド：CSQMaskingConfig.maskAll() と CSQMaskingConfig.unMaskAll()。

Navigator Observer（画面の自動トラッキング）

Observer を追加する前に、pubspec.yaml で使用中のナビゲーションパッケージを確認してください。

  • auto_route → CSQNavigatorAutoRouteObserver を使用してください（下記の AutoRoute セクションを参照）
  • go_router → GoRouter(observers: [...]) から CSQNavigatorObserver を使用してください
  • どちらも使用していない場合 → MaterialApp(navigatorObservers: [...]) から CSQNavigatorObserver を使用してください
標準の Flutter Navigator（MaterialApp / CupertinoApp）
import 'package:contentsquare/csq.dart';

MaterialApp(
  navigatorObservers: [
    CSQNavigatorObserver(
      screenNameProvider: (route) {
        if (route.settings.name == '/profile') return 'User Profile';
        return route.settings.name;
      },
      customVarsProvider: (route) => [
        CustomVar(index: 1, name: 'section', value: 'main'),
      ],
      excludeRouteFromTracking: (route) =>
          route.settings.name?.startsWith('/debug') ?? false,
    ),
  ],
);

3 つのコールバックはすべて省略可能です。指定しない場合、ルート名が画面名として使用されます。

モーダルルート（showDialog、showModalBottomSheet など）は、デフォルトで個別の画面としてトラッキングされます。除外するには excludeRouteFromTracking を使用してください。

GoRouter

追加のパッケージは不要です。GoRouter の observers パラメーターから CSQNavigatorObserver を渡してください。MaterialApp.router から渡すのではありません。

GoRouter(
  observers: [CSQNavigatorObserver()],
  routes: [...],
)

GoRoute で pageBuilder を使用する場合は、MaterialPage に name を設定する必要があります。設定しないと、Observer が名前のないルートを受け取ります。references/common-patterns.md を参照してください。

AutoRoute

AutoRoute は CSQNavigatorObserver と互換性がありません。csq_navigator_auto_route_observer パッケージの CSQNavigatorAutoRouteObserver を使用してください。タブナビゲーションも自動的に処理されます（didInitTabRoute / didChangeTabRoute）。

csq_navigator_auto_route_observer: ^1.1.0 を dependencies に追加し、ルーター設定にアタッチしてください。

import 'package:csq_navigator_auto_route_observer/csq_navigator_auto_route_observer.dart';

MaterialApp.router(
  routerConfig: _appRouter.config(
    navigatorObservers: () => [
      CSQNavigatorAutoRouteObserver(),
    ],
  ),
);

CSQNavigatorObserver と同じ 3 つの省略可能なコールバック（screenNameProvider、customVarsProvider、excludeRouteFromTracking）をサポートしています。コールバックの完全なリファレンスとモーダル除外の例については、references/screen-tracking.md を参照してください。

互換性： AutoRoute >=10.1.0+1 <12.0.0、csq_navigator_auto_route_observer ^1.1.0。

PageView と TabBar（手動トラッキングが必要）

PageView のスワイプや標準の TabBar のタブ変更ではルートがプッシュされないため、Observer は呼び出されません。trackScreenview を手動で呼び出してください。

  • PageView：onPageChanged コールバックを使用します
  • TabBar：TabController.addListener を使用します

コード例の詳細については、references/screen-tracking.md を参照してください。

WebView のトラッキング

WebView は自動ではトラッキングされません。ネイティブアプリと Web コンテンツのセッションを連携させるには、CSQWebViewWrapper でラップし、JavaScript チャネルブリッジを設定する必要があります。

前提条件：

  1. WebView で JavaScript が有効になっていること
  2. WebView で読み込む Web ページに Contentsquare Web Tracking Tag in WebView mode が設定されていること
webview_flutter を使用する場合（JSChannelWebViewWrapperDelegate）
import 'package:contentsquare/csq.dart';
import 'package:webview_flutter/webview_flutter.dart';

webViewController.setJavaScriptMode(JavaScriptMode.unrestricted);

CSQWebViewWrapper(
  delegate: JSChannelWebViewWrapperDelegate(
    addJavaScriptChannel: (WebViewJSChannelHandler handler) {
      webViewController.addJavaScriptChannel(
        handler.channelName,
        onMessageReceived: (jsMessage) {
          handler.onMessageReceived(jsMessage.message);
        },
      );
    },
    builder: (context) {
      return WebViewWidget(controller: webViewController);
    },
  ),
);
flutter_inappwebview を使用する場合（UserScriptWebViewWrapperDelegate）
import 'dart:collection';
import 'package:contentsquare/csq.dart';
import 'package:flutter_inappwebview/flutter_inappwebview.dart';

CSQWebViewWrapper(
  delegate: UserScriptWebViewWrapperDelegate(
    builder: (BuildContext context, String userScript) {
      return InAppWebView(
        initialOptions: InAppWebViewGroupOptions(
          crossPlatform: InAppWebViewOptions(javaScriptEnabled: true),
        ),
        initialUrlRequest: URLRequest(url: Uri.parse(url)),
        initialUserScripts: UnmodifiableListView([
          UserScript(
            source: userScript,
            injectionTime: UserScriptInjectionTime.AT_DOCUMENT_START,
          ),
        ]),
      );
    },
  ),
);

重要：

  • チャネル名には必ず handler.channelName を使用してください（ハードコードしないでください）
  • JavaScript チャネルのコールバックでは、必ず handler.onMessageReceived(...) を呼び出してください
  • UserScript では、必ず injectionTime を AT_DOCUMENT_START に設定してください
  • 基盤となる WebView には、Android では android.webkit.WebView、iOS では WKWebView を使用してください

よくあるパターン

1. エラー処理を含む初期化の全体例
void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await CSQ().start(
    maskingConfig: const CSQMaskingConfig(maskTexts: true, maskTextFields: true),
  );
  await CSQ().optIn();

  FlutterError.onError = (details) {
    CSQ().collectFlutterError(details: details);
  };

  runZonedGuarded(
    () => runApp(const MyApp()),
    (error, stack) => CSQ().collectError(error: error, stackTrace: stack),
  );
}
2. オンデマンドのセッションリプレイ（機密性の高いフロー）
// 1) Disable SR auto-start globally
await CSQ().start(
  startConfig: StartConfig.withEnvironmentId(
    id: 'your-env-id',
    options: const AnalyticsOptions(sessionReplayAutoStart: false),
  ),
);

// 2) Start SR once, when entering the flow you want recorded
await CSQ().startSessionReplay();

// 3) Stop SR when the flow is done.
//    WARNING: this is terminal for the SDK lifetime -- you cannot
//    restart SR after this call. Do NOT wire it to dispose() of
//    short-lived widgets if you may want SR again later in the same session.
await CSQ().stopSessionReplay();

その他のパターン（プロダクト分析のセットアップ、トランザクション、同意フロー、カスタムイベント）については、references/common-patterns.md を参照してください。

iOS アプリ内機能のセットアップ

iOS で Contentsquare のアプリ内機能（スクリーンショットのキャプチャ、SDK ログ、ゾーニング分析）を使用するには、iOS のネイティブ設定が必要です。

  1. ios/Runner/Info.plist に URL スキーム cs-$(PRODUCT_BUNDLE_IDENTIFIER) を追加します。
  2. AppDelegate.swift で CSQ.handle(url: url) を呼び出してディープリンクを処理します。

ネイティブファイルの編集が許可される数少ないケースの 1 つです。

AppDelegate、SceneDelegate、SwiftUI のコードサンプルを含む実装ガイド全文については、references/ios-in-app-features.md を参照してください。

移行

移行手順の全容は references/migration.md にあります。アップグレードを実施する前に、そのファイルを読み込んでください。

お客様の現在の状態参照する移行ガイド
^3.x を使用しており、Contentsquare() シングルトン、ContentsquareRoot、MaskingConfig、ContentsquareNavigatorObserver などを使用している。Legacy Contentsquare API to CSQ (v3.x → v4.x) -- API の名前変更、ContentsquareRoot の削除、ネイティブの AndroidManifest.xml / Info.plist の整理、Swift の Contentsquare.handle( から CSQ.handle( への変更。
^4.1.x を使用しており、configureProductAnalytics(...) および／または削除済みの ProductAnalyticsOptions フィールド（captureVendorId、resumePreviousSession、pruningLookBackWindow など）を使用している可能性がある。4.1.x to 4.5.1 -- 破壊的変更：ProductAnalyticsOptions の 11 フィールドを削除、configureProductAnalytics の非推奨化（2026 年 8 月に削除）、新しい startSessionReplay / stopSessionReplay と sessionReplayAutoStart オプション。

重要な制約

  • IDは次の順序で確認してください：統合前に、ユーザーに （1） Contentsquare の データソース ID を尋ねてください（ヘルスチェックでの回答を再利用します）。新規クライアントにはこれを推奨します。（2） データソース ID がない場合は、環境 ID を尋ねてください。（3） どちらもない場合（または DXA のみを明示的に希望する場合）に限り、StartConfig.dxa() にフォールバックしてください。回答は次のように対応付けます：StartConfig.withDatasourceId(id:) → StartConfig.withEnvironmentId(id:) → StartConfig.dxa()。IDを作り出したり、黙って DXA をデフォルトにしたりしないでください。
  • 例外を除き、ネイティブコードやネイティブ設定には一切手を加えないでください：統合はデフォルトで Dart のみ です。明示的に許可されていない限り、android/、ios/、macos/、windows/、linux/ 配下のファイルを編集しないでください。許可される例外：
    • iOS アプリ内機能の設定：ios/Runner/Info.plist に cs-$(PRODUCT_BUNDLE_IDENTIFIER) URL スキームを追加し、AppDelegate.swift にディープリンクハンドラーを追加します（iOS アプリ内機能の設定セクションを参照）。
    • v3.x から v4.x への移行時のクリーンアップ：AndroidManifest.xml からレガシーな com.contentsquare.android.autostart メタタグを削除し、Info.plist から CSDisableAutostart キーを削除し、Swift の Contentsquare.handle( を CSQ.handle( に名前変更します（references/migration.md を参照）。 これらの範囲外のネイティブ変更が必要な場合は、編集せずに作業を止めてユーザーに確認してください。
  • iOS アプリ内機能は必ず設定してください：新しい統合では毎回、iOS の設定（URL スキームと AppDelegate.swift の CSQ.handle(url:)）を適用してください。詳細なサンプルは iOS アプリ内機能の設定 と references/ios-in-app-features.md を参照してください。
  • ナビゲーションパッケージとウィジェットを検出してください：pubspec.yaml とコードをスキャンします。auto_route の場合は csq_navigator_auto_route_observer をインストールし、_appRouter.config(navigatorObservers: ...) で CSQNavigatorAutoRouteObserver を使用します。go_router の場合は GoRouter(observers: [...]) で CSQNavigatorObserver を使用します（MaterialApp.router ではありません）。どちらも使用されていない場合は、MaterialApp(navigatorObservers: [...]) で CSQNavigatorObserver を使用します。さらに、PageView と TabBar ウィジェットはルートをプッシュしません。そのため、onPageChanged／TabController.addListener で手動の trackScreenview が必要です。
  • WebView をスキャンしてください：統合時に、コードベース内の既存の WebView 使用箇所（webview_flutter、flutter_inappwebview、WebViewWidget、InAppWebView）を検索してください。WebView は自動ではトラッキングされません。すべての WebView を CSQWebViewWrapper と適切なデリゲートでラップする必要があります。この手順を省略しないでください。
  • まず start() を呼び出してください：他のすべての CSQ メソッドを使うには、事前に start() が呼び出されている必要があります。
  • Contentsquare ではなく CSQ を使用してください：Contentsquare クラスは非推奨です。必ず CSQ() を使用してください。
  • configureProductAnalytics は非推奨です（削除予定：2026年8月）。代わりに CSQ().start(startConfig: StartConfig.withEnvironmentId(...)) を使用してください。両方を併用しないでください。非推奨 API が優先され、start(startConfig: ...) を黙って上書きします。
  • ProductAnalyticsOptions ではなく AnalyticsOptions を使用してください：後者は後方互換性のために残されている typedef です。新しいコードでは AnalyticsOptions を使用してください。現在は DXA にも適用されます。
  • プラットフォームのサポート：Android と iOS のみです。Web／デスクトップでは何もしない実装が返されます。
  • Flutter のバージョン：Flutter >= 3.27.0、Dart >= 3.6.0 が必要です。
  • プロパティの型：イベント／ユーザープロパティに使用できるのは String、num、bool のみです。
  • DynamicVar の制限：キーは最大49文字（< 50 のアサーションあり）、文字列値は最大255文字（< 256 のアサーションあり）、整数値の範囲は 0..2^32-1 です。
  • userIdentifier：identify() と sendUserIdentifier() の両方で、最大100文字を推奨します。
  • プライバシー：オプトインを自動で行わないでください。必ず同意フローを実装してください。
  • PII：画面名、イベント名、プロパティにメールアドレス、パスワード、実名を渡さないでください。
  • 環境 ID：ハードコードしないでください。設定または環境変数を使用してください。
  • iOS：統合前に iOS compatibility docs を確認してください。

参考資料

コメント

Markdown 対応