Swift 向け Unified SDK

これは、Amplitude Unified SDK for Swiftの公式ドキュメントです。

Unified SDKはAmplitudeの既存のSDKをラップし、複数のAmplitude製品を一緒に使用するためのシンプルなインターフェイスを提供します。これには以下が含まれます。

SDKをインストールする

依存関係をPodfile：に追加してください。
bash
```
pod 'AmplitudeUnified', '~> 0.0.3'
```
プロジェクトディレクトリでpod install実行します。

SDKの初期化

計装を行う前にSDKを初期化してください。 AmplitudeプロジェクトのAPIキーを入力してください。

// Basic initialization with default configurations
let amplitude = Amplitude(
    apiKey: "YOUR_API_KEY"
)
// Advanced initialization with custom configurations
let amplitude = Amplitude(
    apiKey: "YOUR_API_KEY",
    serverZone: .US,
    instanceName: "default_instance",
    analyticsConfig: AnalyticsConfig(),
    experimentConfig: ExperimentPlugin.Config(),
    sessionReplayConfig: SessionReplayPlugin.Config(),
    logger: ConsoleLogger()
)

SDK を設定する

アナリティクスの設定

Unified SDK はアナリティクス設定オブジェクトを受け入れます。設定の詳細については、アナリティクス SDK のドキュメントを参照してください。

let analyticsConfig = AnalyticsConfig(
    flushQueueSize: 30,
    flushIntervalMillis: 30000,
    trackingOptions: TrackingOptions().disableTrackCity().disableTrackIpAddress(),
    minTimeBetweenSessionsMillis: 300000,
    autocapture: [.sessions, .appLifecycles, .screenViews]
)
let amplitude = Amplitude(
    apiKey: "YOUR_API_KEY",
    analyticsConfig: analyticsConfig
)

実験構成

Unified SDK は実験設定オブジェクトを受け入れます。設定の詳細については、実験 SDK のドキュメントを参照してください。

let experimentConfig = ExperimentPlugin.Config(
    serverUrl: "https://api.lab.amplitude.com",
    debug: true,
    fetchTimeoutMillis: 10000
)
let amplitude = Amplitude(
    apiKey: "YOUR_API_KEY",
    experimentConfig: experimentConfig
)

セッションリプレイの設定

Unified SDK は、適切なデフォルト値を使用してセッションリプレイ SDK を設定します。より高度な設定オプションについては、セッションリプレイ SDK のドキュメントを参照してください。

セッションリプレイはiOSでのみ利用できます。macOS、tvOS、watchOS、visionOSでは利用できません。

#if canImport(AmplitudeSessionReplay)
let sessionReplayConfig = SessionReplayPlugin.Config(
    sampleRate: 1.0
)
let amplitude = Amplitude(
    apiKey: "YOUR_API_KEY",
    sessionReplayConfig: sessionReplayConfig
)
#endif

SDK を使用する

Unified SDKを使用すると、単一のインターフェースから個々のSDKのすべての機能にアクセスできます。

アナリティクス

Unified SDK は、アナリティクス SDK のすべての機能を直接公開します。メソッドの完全なリストについては、アナリティクス SDK のドキュメントを参照してください。

// Track an event
amplitude.track(eventType: "Button Clicked", eventProperties: ["button_id": "sign_up"])
// Set user properties
let identify = Identify()
identify.set(property: "plan", value: "premium")
amplitude.identify(identify: identify)
// Set user ID
amplitude.setUserId(userId: "user@example.com")

実験

Unified SDKは、Amplitudeインスタンスを作成するときにExperiment SDKを初期化および設定します。実験クライアントには、experimentプロパティを通じてアクセスします。

// Fetch variants for the current user
guard let experiment = amplitude.experiment else {
    return
}
experiment.fetch(user: nil) { experiment, error in
    if let error = error {
        print("Error fetching variants: \(error)")
        return
    }
    // Get a variant for a flag
    let variant = experiment.variant("my-flag")
    print("Variant: \(variant.value)")
    // Evaluate a flag locally
    let localVariant = experiment.variant("local-flag", fallback: Variant("default"))
    print("Local variant: \(localVariant.value)")
    // Exposure tracking is automatic when you call variant()
    // But you can also track exposures manually
    experiment.exposure(key: "my-flag")
}

セッションリプレイ

Unified SDKは、iOSでAmplitudeインスタンスを作成するときにセッションリプレイSDKを初期化および設定します。セッションリプレイは、macOS、tvOS、watchOS、またはvisionOSではご利用いただけません。

#if canImport(AmplitudeSessionReplay)
// Session Replay is automatically initialized and configured.
// Access the Session Replay client through the sessionReplay property.
// Start (or resume) capture
amplitude.sessionReplay?.start()
// Stop (pause) capture. Call start() again to resume; both methods act on the same instance.
amplitude.sessionReplay?.stop()
#endif

高度なトピック

このセクションの手順に従って、ID 管理などの機能を有効にしてください。

アイデンティティ管理

Unified SDKは、すべてのAmplitudeプロダクト間でユーザーIDを同期させる統合ID管理システムを提供します。Amplitudeメソッドを使用してユーザーIDまたはデバイスIDを設定すると、SDKは変更内容を実験とセッションリプレイに反映します。

// Set user ID - automatically propagated to all products
amplitude.setUserId(userId: "user@example.com")
// Set device ID - automatically propagated to all products
amplitude.setDeviceId(deviceId: "custom-device-id")
// Reset user - clears user ID and generates a new device ID
amplitude.reset()
// Access the current identity
let userId = amplitude.identity.userId
let deviceId = amplitude.identity.deviceId

ユーザープロパティ

Unified SDK は、操作セットを識別するユーザープロパティのキャッシュを保持します。このキャッシュを使用すると、現在のユーザープロパティ状態にいつでもアクセスできます。

// Set user properties
let identify = Identify()
identify.set(property: "plan", value: "premium")
identify.set(property: "age", value: 25)
amplitude.identify(identify: identify)
// Access the current user properties
let userProperties = amplitude.identity.userProperties
print("User plan: \(userProperties["plan"] ?? "none")")
print("User age: \(userProperties["age"] ?? 0)")
// Clear all user properties
let clearIdentify = Identify()
clearIdentify.clearAll()
amplitude.identify(identify: clearIdentify)

デバッグ

デバッグログを有効にするには、アナリティクス設定でログレベルをDEBUGに設定します。

let analyticsConfig = AnalyticsConfig(
    // Other configuration options...
)
let amplitude = Amplitude(
    apiKey: "YOUR_API_KEY",
    analyticsConfig: analyticsConfig,
    logger: ConsoleLogger(logLevel: LogLevelEnum.debug.rawValue)
)

一般的な問題

Unified SDK の実装が期待どおりに機能しない場合は、以下の一般的な問題を考慮してください。

セッションリプレイはiOS以外のプラットフォームでは機能しません

セッションリプレイはiOSでのみ利用できます。 macOS、tvOS、watchOS、またはvisionOSでは利用できません。Unified SDK はプラットフォームを検出し、iOSでのみセッションリプレイを初期化します。

イベントはAmplitudeに表示されない

イベントがAmplitudeに表示されない場合：

正しいAPIキーを使用していることを確認してください。
デバイスがインターネットに接続されていることを確認してください。
イベントがフラッシュされるまで十分な時間をとってください（デフォルト時間は30秒です）。
ログをチェックしてエラーメッセージを確認してください。

実験フラグが取得されない

実験フラグが取得できない場合:

amplitude.experimentがnilでないことを確認してから、fetch(user:completion:)を呼び出してください。
ユーザーIDまたはデバイスIDが正しく設定されていることを確認してください。
Amplitude Experimentダッシュボードでフラグが正しく設定されていることを確認してください。
実験SDKからのエラーメッセージをログで確認してください。

移行ガイド

個々のAmplitude SDKを別々に使用する場合は、以下の手順に従ってUnified SDKに移行してください。

Unified SDKの依存関係をプロジェクトに追加します。
個々のSDKの依存関係（AmplitudeSwift、実験、AmplitudeSessionReplay）を削除します。
初期化コードをUnified SDKの初期化コードに置き換えてください。
Unified SDKインターフェイスを使用するようにAPI呼び出しを更新します。

移行前

// Analytics SDK
let amplitude = Amplitude(configuration: Configuration(
    apiKey: "YOUR_API_KEY",
    flushQueueSize: 30,
    flushIntervalMillis: 30000
))
// Experiment SDK
let experimentClient = Experiment.initialize(
    apiKey: "YOUR_API_KEY",
    config: ExperimentConfigBuilder()
        .serverUrl("https://api.lab.amplitude.com")
        .build()
)
// Session Replay SDK
let sessionReplay = SessionReplayPlugin(config: SessionReplayPlugin.Config(
    sampleRate: 1.0
))
amplitude.add(plugin: sessionReplay)

移行後

let analyticsConfig = AnalyticsConfig(
    flushQueueSize: 30,
    flushIntervalMillis: 30000
)
let experimentConfig = ExperimentPlugin.Config(
    serverUrl: "https://api.lab.amplitude.com"
)
let sessionReplayConfig = SessionReplayPlugin.Config(
    sampleRate: 1.0
)
let amplitude = Amplitude(
    apiKey: "YOUR_API_KEY",
    analyticsConfig: analyticsConfig,
    experimentConfig: experimentConfig,
    sessionReplayConfig: sessionReplayConfig
)

Was this helpful?