iOS Swift SDK

これは、Amplitude Analytics iOS SDKの公式ドキュメントです。

SDK をインストールする

SDKの初期化

イベントを計測する前に、SDKを初期化してください。 Amplitudeプロジェクト用のAPIキーが必要です。

let amplitude = Amplitude(configuration: Configuration(
    apiKey: AMPLITUDE_API_KEY,
    autocapture: .all
))

SDK を設定する

イベントを追跡

イベントは、ユーザーがアプリケーションとどのように対話するかを表します。 たとえば、「ボタンのクリック」は、追跡したいアクションかもしれません。

let event = BaseEvent(
    eventType: "Button Clicked",
    eventProperties: ["my event prop key": "my event prop value"]
)
amplitude.track(event: event)

基本的な追跡イベントを計装する別の方法：

amplitude.track(
    eventType: "Button Clicked",
    eventProperties: ["my event prop key": "my event prop value"]
)

Identify

Identifyは、イベントを送信することなく、特定のユーザーのユーザープロパティを設定します。SDKは、個々のユーザープロパティに対するset、setOnce、unset、add、append、prepend、preInsert、postInsert、remove、clearAllなどの操作をサポートしています。 提供された Identify インターフェイスを使用して操作を宣言します。 単一の Identify オブジェクト内で複数の操作をチェーンできます。 次に、IdentifyオブジェクトをAmplitudeクライアントに渡し、サーバーに送信します。

identify メソッドを使用してユーザーの ID を処理できます。 これらの方法を適切に使用すると、デバイス、ブラウザ、その他のプラットフォーム間でイベントが移動する際に、イベントを適切なユーザーに結び付けることができます。 これらのユーザープロパティ操作を含む識別コールをAmplitudeサーバーに送信し、ユーザーのイベントを特定のユーザープロパティと結び付けます。

let identify = Identify()
identify.set(property: "color", value: "green")
amplitude.identify(identify: identify)

すべてのユーザープロパティを消去する

ユーザーからすべてのユーザープロパティを削除する場合に使用します。clearAll 操作は元に戻せないため、clearAll注意して使用してください。

let identify = Identify()
identify.clearAll()
amplitude.identify(identify: identify)

自動キャプチャ

リリースv1.8.0以降、SDKは手動による計装なしでより多くのイベントを追跡できるようになりました。 以下のイベントを自動的に追跡するようにSDKを設定します。

• セッション
• アプリケーションのライフサイクル
• スクリーンビュー
• 要素のインタラクション
• フラストレーションの相互作用
  • レイジクリック
  • デッドクリック数
• ネットワーク要求

自動キャプチャイベントのトラッキングを開始するようにAmplitudeを設定できます。 それ以外の場合は、設定を省略してセッショントラッキングのみを有効にしておくことができます。

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: [.sessions, .appLifecycles, .screenViews, .networkTracking]
))

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .appLifecycles 	// or use `[]` to disable Autocapture.
))

自動キャプチャ用のリモート設定

リリースv1.10.0以降、SDKは自動キャプチャ設定のリモート設定をサポートしています。この機能を使用すると、初期化後にアプリを更新することなく自動キャプチャ設定を更新できます。

デフォルトでは、Amplitudeは自動キャプチャのリモート設定を有効にしています。ITを無効にするには、設定でenableAutoCaptureRemoteConfigをfalseに設定します。

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: [.sessions, .appLifecycles, .screenViews],
    enableAutoCaptureRemoteConfig: false
))

リモート設定を有効にすると、SDKはプロジェクト内の自動キャプチャ設定の更新を確認します。SDKが更新を検出した場合、自動的に更新を適用します。これにより、次のことが可能になります。

• 特定の自動キャプチャ機能をリモートで有効または無効にできます。
• ユーザーがアプリを更新する必要なく、自動キャプチャ設定を変更できます。

リモート設定を通じて行われた変更は、将来のイベントに影響を及ぼし、Amplitudeがすでに追跡しているイベントには適用されません。

セッションを追跡する

Amplitudeはデフォルトでセッション追跡を有効にします。autocapture設定に含めると、SDKがセッションイベントを追跡するように明示的に設定したり、他の自動キャプチャ設定でセッションイベントトラッキングを有効にしたりAutocaptureOptions.sessionsできます。

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .sessions
))

セッション追跡の詳細については、「ユーザーセッション」を参照してください。

アプリケーションのライフサイクルを追跡

Amplitudeがアプリケーションのライフサイクルイベントを追跡できるようにするには、autocapture設定にAutocaptureOptions.appLifecyclesを含めます。

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .appLifecycles
))

この設定を有効にすると、Amplitudeは以下のイベントを追跡します：

• [Amplitude] Application Installed：このイベントは、インストール後にユーザーが初めてアプリケーションを開いた際、内部でUIApplicationDidFinishLaunchingNotification通知を監視することで発生します。
• [Amplitude] Application Updated：このイベントは、ユーザーがアプリケーションを更新した後にアプリケーションを開いた際、内部でUIApplicationDidFinishLaunchingNotification通知を監視することで発生します。
• [Amplitude] Application Opened：このイベントは、ユーザーが初回起動後にアプリケーションを起動またはフォアグラウンドにした際、内部でUIApplicationDidFinishLaunchingNotificationまたはUIApplicationWillEnterForegroundNotification通知を監視することで発生します。
• [Amplitude] Application Backgrounded：このイベントは、ユーザーがアプリケーションをバックグラウンドにした際に、内部でUIApplicationDidEnterBackgroundNotification通知を監視することで発生します。

画面ビューを追跡

Amplitudeが画面ビューイベントを追跡できるようにするには、autocapture設定にAutocaptureOptions.screenViewsを含めます。

// UIKit
let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .screenViews
))
// Swift UI
let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: []
))
amplitude.track(ScreenViewedEvent(screenName: "Screen Name"))

この設定を有効にすると、Amplitudeは[Amplitude] Screen Viewedイベントを追跡し、このイベントの画面名プロパティを、最上位のビューコントローラのクラス名に設定します。 Amplitudeは、コントローラクラスのメタデータviewDidAppearメソッドswizzlingからこの値を読み取ります。

ネットワークリクエストの追跡

Amplitudeがネットワークリクエストを追跡できるようにするには、autocapture設定にAutocaptureOptions.networkTrackingを含めます。

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .networkTracking
))

デフォルト設定では、SDKはステータスコード500から599までの、すべてのホスト（*.amplitude.comを除く）からのネットワークリクエストを追跡します。 トラッキング動作をカスタマイズするには、Configuration.networkTrackingOptionsをNetworkTrackingOptionsに設定してください。

captureRules: [
    .init(hosts: ["*"], statusCodeRange: "400-499,500-599"),
    .init(hosts: ["*.example.com", "example.com"], statusCodeRange: "0,500-599"),
]

デフォルト設定では、*.amplitude.com以外のすべてのホストを、ステータスコード500～599を除いて追跡します。

使用例：

// Style 1: Use the default configuration and append a new rule
let networkTrackingOptions = NetworkTrackingOptions.default // contain a rule for all hosts, statusCodeRange: "500-599"
networkTrackingOptions.captureRules.append(
    .init(hosts: ["*.example.com", "example.com"], statusCodeRange: "0,500-599")
)
networkTrackingOptions.ignoreHosts.append("notmyapi.com")
let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .networkTracking,
    networkTrackingOptions: networkTrackingOptions,
))
// Style 2: Create a new configuration with a custom rule
let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .networkTracking,
    networkTrackingOptions: .init(
        captureRules: [
            .init(hosts: ["*"]), // all hosts, statusCodeRange: "500-599"
            .init(hosts: ["*.example.com", "example.com"], statusCodeRange: "0,400-599"),
        ],
        ignoreHosts: ["notmyapi.com"]
    ),
))

この設定を有効にすると、Amplitudeはアプリケーションがネットワーク要求を行うたびに[Amplitude] Network Requestイベントを追跡します。 SDKは、URL読み込みシステムのメソッドをスウィズルして、ネットワークアクティビティを計測します。

@_spi(NetworkTracking) import AmplitudeSwift
let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .networkTracking,
    networkTrackingOptions: .init(
        captureRules: [
            .init(hosts: ["*"]), // all hosts, statusCodeRange: "500-599"
            .init(urls: [.regex("^https://example\\.com/api/.*"), .exact("https://example.com/api2/status")],
                  methods: ["POST"],
                  statusCodeRange: "0,400-599",
                  requestHeaders: .init(allowlist: ["Link", "X-API-Key"]),
                  responseHeaders: .init(allowlist: ["Link", "X-API-Key"], captureSafeHeaders: false),
                  requestBody: .init(allowlist: ["user/*", "product/**/id"]),
                  responseBody: .init(allowlist: ["profile/**"], excludelist: ["**/password"])),
        ],
        ignoreHosts: ["notmyapi.com"],
        ignoreAmplitudeRequests: true
    ),
))

ディープリンクを追跡する

ディープリンクのトラッキングは自動化されていません。 ディープリンクを追跡するには、対応するイベントを追跡します。

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY"
))
amplitude.track(DeepLinkOpenedEvent(url: URL()))
amplitude.track(DeepLinkOpenedEvent(url: "url", referrer:"referrer"))
amplitude.track(DeepLinkOpenedEvent(activity: activity))

AmplitudeはURLとリファラー情報を使用して[Amplitude] Deep Link Openedイベントを追跡します。

要素のインタラクションを追跡する

Amplitudeは、UIKitアプリケーション内のUIControl要素およびUIGestureRecognizerオブジェクトに対するユーザーのインタラクションを追跡できます。 このオプションを有効にするには、autocapture設定にAutocaptureOptions.elementInteractionsを含める必要があります。

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .elementInteractions
))

この設定を有効にすると、ユーザーがアプリケーション内の要素とインタラクションを行うたびに、Amplitudeが[Amplitude] Element Interactedイベントを追跡します。 このSDKは、UIApplication.sendAction(_:to:from:for:)メソッドとUIGestureRecognizer.stateプロパティのセッターをスウィズル処理し、それぞれアプリケーション内のUIControlアクションメソッドとUIGestureRecognizerを計測対象とします。

フラストレーションのやり取りを追跡する

バージョン1.15.0+で利用可能です。

Amplitudeは、UIKitアプリケーション内のUIControl要素やUIGestureRecognizerオブジェクトとのフラストレーションインタラクション（レイジクリックやデッドクリック）を追跡できます。 このオプションを有効にするには、autocapture設定にAutocaptureOptions.frustrationInteractionsを含める必要があります。

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .frustrationInteractions
))

interactionsOptionsの設定では、InteractionsOptionsオブジェクトを受け取り、レイジクリックやデッドクリックを捕捉するためのオプションを設定します。

let amplitude = Amplitude(configuration: Configuration(
    apiKey: "API_KEY",
    autocapture: .frustrationInteractions,
    interactionsOptions: .init(
        rageClick: .init(enabled: true),
        deadClick: .init(enabled: true)
    )
))

レイジクリックとは、1秒間に同じ要素に対して4回以上発生し、隣接するクリック間の距離が50ポイント以内のユーザー操作を指します。

レイジクリックが発生すると、Amplitudeはその[Amplitude] Rage Clickイベントを追跡します。

デッドクリックとは、インタラクティブな要素をタップしても、その後3秒間に目に見える変化が生じないことを指します。

デッドクリックが発生すると、Amplitudeはその[Amplitude] Dead Clickイベントを追跡します。

ビューを無視する

特定の を怒りクリックやデッドクリックの検出から除外するには、ビューで UIView``amp_ignoreInteractionEvent(rageClick:deadClick:)を呼び出します。 両方のパラメータのデフォルト値は true です。 このメソッドはUIKitビューにのみ適用されます。

// Ignore both rage clicks and dead clicks on this view.
myView.amp_ignoreInteractionEvent()
// Or ignore only dead clicks.
myView.amp_ignoreInteractionEvent(rageClick: false, deadClick: true)

ユーザーグループ

Amplitudeでは、ユーザーをグループに割り当てたり、それらのグループに対して「ユニーク数による集計」などのクエリを実行したりすることができます。 少なくとも1人のグループメンバーが特定のイベントを実行した場合、そのグループもカウントに含まれます。

たとえば、「orgId」を使用して、ユーザーが所属する組織に基づいてユーザーをグループ化したい場合などです。 Joeは'orgId' '10'に属し、Sueは'orgId' '15'に属しています。SueとJoeはどちらも特定のイベントを実行します。 イベントセグメンテーションチャートでその組織をクエリできます。

グループを設定する際には、groupTypeとgroupNameを定義してください。前の例では、「orgId」はgroupTypeで、「10」と「15」はgroupNameの値です。 groupTypeのもう1つの例としては、「tennis」や「baseball」などのgroupName値を持つ「sport」があります。

グループを設定すると、groupType:groupNameもユーザープロパティとして設定され、そのユーザーのgroupTypeに設定されている既存のgroupName値と対応するユーザープロパティ値が上書きされます。groupTypeは文字列であり、groupNameはユーザーが複数のグループに属していることを示すために文字列または文字列の配列を受け入れます。

// set group with a single group name
amplitude.setGroup(groupType: "orgId", groupName: "15")

// set group with multiple group names
amplitude.setGroup(groupType: "sport", groupName: ["tennis", "soccer"])

また、groupsを含むEventオブジェクトをtrackに渡すことで、イベントレベルのグループを設定することもできます。 イベントレベルのグループの場合、グループの指定はログに記録する特定のイベントにのみ適用され、setGroup で明示的に設定しない限り、ユーザーに永続することはありません。

amplitude.track(
    event: BaseEvent(
        eventType: "event type",
        eventProperties: [
            "eventPropertyKey": "eventPropertyValue"
        ],
        groups: ["orgId": "15"]
    )
)

グループ識別

Group Identify API を使用して、特定のグループのプロパティを設定または更新します。次の点に注意してください。

• 更新は将来のイベントにのみ影響を与え、過去のイベントを更新することはありません。
• 最大5つの固有のグループタイプと合計10のグループを追跡できます。

groupIdentifyメソッドは、グループタイプの文字列パラメータ、グループ名のオブジェクトパラメータ、およびAmplitudeがグループに適用するIdentifyオブジェクトを受け取ります。

let groupType = "plan"
let groupName = "enterprise"
let identify = Identify().set(property: "key", value: "value")
amplitude.groupIdentify(groupType: groupType, groupName: groupProperty, identify: identify)

収益の追跡

Amplitudeはユーザーが生み出した収益を追跡できます。 Amplitudeは、個別の収益オブジェクトを通じて収益を追跡します。これらのオブジェクトには、AmplitudeのイベントセグメンテーションとレベニューLTVチャートで使用される特別なフィールドがあります。これにより、Amplitudeはプラットフォーム内の収益に関連するデータを自動的に表示できます。 収益オブジェクトは、以下の特別なプロパティとeventPropertiesフィールドを通じて、ユーザー定義のプロパティをサポートしています。

let revenue = Revenue()
revenue.price = 3.99
revenue.quantity = 3
revenue.productId = "com.company.productId"
amplitude.revenue(revenue: revenue)

カスタムユーザーID

アプリに独自のログインシステムがあり、ユーザーを追跡したい場合は、いつでもsetUserIdを呼び出してください。

amplitude.setUserId(userId: "user@amplitude.com")

ヘルパーメソッドgetUserId()を使用して、現在のuserIdの値を取得します。

let userId = amplitude.getUserId()

カスタムデバイスID

deviceIdを使用して、新しいデバイスIDを割り当てることができます。 カスタムデバイスIDを設定する際は、その値が十分に一意であることを確認してください。 AmplitudeはUUIDの使用を推奨しています。

amplitude.setDeviceId(deviceId: NSUUID().uuidString)

カスタムストレージ

Amplitudeで定義された場所以外にデータを保存するには、Storageプロトコルを実装し、設定でstorageProviderを設定することで、独自のストレージをカスタマイズしてください。

すべてのiOSアプリケーションはそれ自身のためにストレージの一部を取得します。つまり、他のアプリケーションと競合することなく、アプリケーションのファイルをそこで読み書きできます。 デフォルトでは、Amplitudeはこのファイルストレージを使用し、アプリの「Documents」ディレクトリ内に「Amplitude」というプレフィックスを持つフォルダを作成します。ネイティブのiOS「ファイル」アプリでDocumentsフォルダを公開する必要があり、「Amplitude」という接頭辞を持つフォルダを公開したくない場合は、独自のストレージプロバイダをカスタマイズして、初期化時にイベントを永続化できます。

Amplitude(
    configuration: Configuration(
        apiKey: AMPLITUDE_API_KEY,
        storageProvider: YourOwnStorage() // YourOwnStorage() should implement Storage
    )
)

ユーザーがログアウトしたときにリセットする

resetは、ログアウト後にユーザーを匿名化するためのショートカットです。以下の方法で行います：

• userIdをnullに設定します。
• 現在の設定に基づいてdeviceIdを新しい値に設定します。

空のuserIdと完全に新しいdeviceIdの場合、現在のユーザーはダッシュボードに新しいユーザーとして表示されます。

amplitude.reset()

プラグイン

プラグインを使用すると、イベントプロパティを変更したり（エンリッチメントタイプ）、サードパーティAPIに送信したり（送信先タイプ）、Amplitude SDKの動作を拡張できます。プラグインとは、メソッドsetup()とexecute()を持つオブジェクトです。

プラグインの種類

SDK は固定された順序で各イベントにプラグインを適用します。beforeつまり、プラグインが最初に実行され、次にenrichmentプラグインが実行され、次にdestinationプラグインが実行されます。 その他のプラグインタイプ(例: observe)は、このパイプラインの外で実行されます。

• beforeプラグイン(PluginType.before)は、すべてのエンリッチメントプラグインの前に実行されます。ITを使用して、他のプラグインが読み取る前にイベントフィールドを早期に設定または保護します。ITはエンリッチメントプラグインと同じ形状で、typeに設定されています。PluginType.before
• enrichmentプラグイン (PluginType.enrichment) は、イベントプロパティを追加するなど、各イベントを通過させる際に変更または拡張します。 拡張タイプのプラグイン例を参照してください。
• destinationプラグイン (PluginType.destination) は、イベントを送信先 (サードパーティ API など) に送信し、パイプラインを終了します。送信先タイプのプラグイン例を参照してください。
• プラグイン (PluginType.observe) はイベントパイプラインの外で実行されます。 observeイベントを処理する代わりに、それは onUserIdChanged、 onDeviceIdChanged、 onSessionIdChanged、onOptOutChanged および を上書きすることで、ID の変更に対応します。

次の Observe プラグインは、ユーザーがログインまたはログアウトしたときに反応します。

class LoginObserverPlugin: ObservePlugin {
    override func onUserIdChanged(_ userId: String?) {
        // React to login or logout.
    }
}
amplitude.add(plugin: LoginObserverPlugin())

プラグインのセットアップ

このメソッドには、プラグインを使用できるように準備するためのロジックが含まれており、amplitudeインスタンスをパラメータとして持っています。 このメソッドの典型的な用途は、プラグインの依存関係をインスタンス化することです。SDKは、amplitude.add()を通じてプラグインをクライアントに登録する際に、このメソッドを呼び出します。

Plugin.execute

このメソッドにはイベントを処理するためのロジックが含まれており、eventインスタンスをパラメータとして持っています。 拡張タイプのプラグインとして使用する場合、期待される戻り値は変更されたイベントまたは拡張されたイベントです。 送信先タイプのプラグインとして使用する場合、期待される戻り値はnullです。 SDK は、Identify、GroupIdentify、および Revenue イベントを含む各イベントに対してこのメソッドを呼び出します。これらのイベントはクライアントインターフェイスを使用して計測されます。

エンリッチメントタイプのプラグイン例

これは、追加のイベントプロパティを追加することにより、計測された各イベントを変更するプラグインの例です。

class EnrichmentPlugin: Plugin {
    let type: PluginType
    var amplitude: Amplitude?
    init() {
        self.type = PluginType.enrichment
    }
    func setup(amplitude: Amplitude) {
        self.amplitude = amplitude
    }
    func execute(event: BaseEvent?) -> BaseEvent? {
        event?.sessionId = -1
        if event?.eventProperties == nil {
            event?.eventProperties = [:]
        }
        event?.eventProperties?["event prop key"] = "event prop value"
        return event
    }
}
amplitude.add(plugin: EnrichmentPlugin())

送信先タイプのプラグインの例

送信先プラグインでは、track()、identify()、groupIdentify()、revenue()およびflush()関数を上書きできます。

class TestDestinationPlugin: DestinationPlugin {
    override func track(event: BaseEvent) -> BaseEvent? {
        return event
    }
    override func identify(event: IdentifyEvent) -> IdentifyEvent? {
        return event
    }
    override func groupIdentify(event: GroupIdentifyEvent) -> GroupIdentifyEvent? {
        return event
    }
    override func revenue(event: RevenueEvent) -> RevenueEvent? {
        return event
    }
    override func flush() {
    }
    override func setup(amplitude: Amplitude) {
        self.amplitude = amplitude
    }
    override func execute(event: BaseEvent?) -> BaseEvent? {
        return event
    }
}

プラグインを削除する

プラグインがイベントを処理することを停止するには、同じプラグインインスタンスを remove(plugin:) に渡します。

let plugin = EnrichmentPlugin()
amplitude.add(plugin: plugin)
// Later, remove it.
amplitude.remove(plugin: plugin)

トラブルシューティングとデバッグ

設定とペイロードが正確であることを確認し、デバッグ中に異常なメッセージがないかをチェックしてください。 すべてが正しいようであれば、flushQueueSizeまたはflushIntervalMillisの値を確認してください。 SDKはデフォルトでイベントをキューイングし、バッチ処理で送信するため、サーバーへ即座に送信されるわけではありません。 SDKがイベントをサーバーに送信するのを待ってから、グラフでイベントを確認してください。

ログ

• デバッグ中に有用な情報を収集するには、ログレベルをdebugに設定してください。
• LoggerProviderからloggerProviderのクラスをカスタマイズし、本番環境のサーバーにエラーメッセージを記録するなどの独自のロジックを実装してください。

プラグイン

送信先プラグインを使用して、設定値やイベントのペイロードをサーバーに送信する前に出力してください。 logLevelをdebugに設定し、以下をプロジェクトにコピーしてTroubleShootingPluginから、プラグインをAmplitudeインスタンスに追加してください。

SwiftUI TroubleShootingPlugin の例。

イベントコールバック

イベントコールバックは、SDKがイベントを送信した後に実行されます（成功したイベントと失敗したイベントの両方について）。このメソッドを使用して、イベントステータスとメッセージをモニターできます。詳細については、「設定」>「コールバック」を参照してください。

高度なトピック

ユーザーセッション

Amplitudeは、アプリがフォアグラウンドに移動したとき、またはSDKがバックグラウンドでイベントを追跡したときにセッションを開始します。 アプリがバックグラウンドでsetMinTimeBetweenSessionsMillis()で設定された時間以上経過し、イベントを追跡しない場合、セッションは終了します。 configuration.defaultTrackingやconfiguration.autocaptureでセッション追跡が有効になっているかどうかに関わらず、アプリがフォアグラウンドにある間はセッションが継続します。

アプリがフォアグラウンドに入ると、Amplitudeはセッションの開始を追跡し、setMinTimeBetweenSessionsMillis()に基づいてカウントダウンを開始します。 Amplitudeは、新しいイベントを追跡するたびにセッションを延長し、カウントダウンを再開します。 カウントダウンが期限切れになると、Amplitudeは次のイベントまで待機してセッション終了イベントを追跡します。

Amplitudeはデフォルトでセッションイベントのユーザープロパティを設定しません。 これらのプロパティを追加するには、identify()およびsetUserId()を使用します。 Amplitudeはユーザープロパティの状態を集約し、device_idやuser_idに基づいてユーザーとイベントを関連付けます。

Amplitudeがセッションを管理する方法により、いくつかのシナリオでは、SDKが期待どおりに動作してもイベントが欠落しているように見えたり、セッション追跡が不正確になる可能性があります。

• ユーザーがアプリに戻らなかった場合、Amplitudeはセッション開始イベントに対応するようにセッション終了イベントを追跡しません。
• バックグラウンドでイベントを追跡する場合、Amplitudeはセッション時間をユーザーがフォアグラウンドでアプリに費やす時間よりも長いと認識する場合があります。
• 最後のイベントとセッション終了イベントの間にユーザープロパティを変更した場合、セッション終了イベントには更新されたユーザープロパティが反映されます。このプロパティは、同じセッション内のイベントに関連付けられた他のプロパティとは異なる場合があります。この問題に対処するには、エンリッチメントプラグインを使用して、セッション終了イベント時にevent['$skip_user_properties_sync']をtrueに設定します。これにより、Amplitudeがその特定のイベントについてプロパティを同期するのを防ぐことができます。 詳細については、『コンバータ設定リファレンス』の記事にある $skip_user_properties_sync を参照してください。

Amplitudeはイベントをセッションごとにグループ化します。 同じセッション内で記録されたイベントは、同じsession_idを共有します。 Amplitudeではセッションが自動的に処理されるため、startSession()やendSession()を手動で呼び出す必要はありません。

Amplitudeがセッションを延長する時間枠を調整できます。 デフォルトのセッション有効期限は5分です。

ヘルパーメソッドgetSessionIdを使用して、現在のsessionIdの値を取得します。

let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: AMPLITUDE_API_KEY,
        minTimeBetweenSessionsMillis: 1000
    )
)

また、イベントをセッション外として追跡することもできます。 セッション外のイベントの-1はsessionIdとなり、次のように動作します：

1. 現在のセッションの一部ではありません。
2. 現在のセッションを延長しないでください。
3. 新しいセッションを開始しないでください。
4. 以降のイベントのためにsessionIdを変更しないでください。

潜在的なユースケースとしては、プッシュ通知から追跡されるイベントがあります。これは通常、顧客のアプリの使用状況とは関係ありません。

track(event, options)またはidentify(identify, options)を呼び出す際に、イベントをセッション外としてマークするには、EventOptionsでsessionIdを-1に設定してください。

let outOfSessionOptions = EventOptions(sessionId: -1)
amplitude.identify(
    event: Identify().set(property: "user-prop", value: true),
    options: outOfSessionOptions
)
amplitude.track(
    event: BaseEvent(eventType: "Button Clicked"),
    options: outOfSessionOptions
)

セッション ID を手動で設定するには、ミリ秒単位の Unix タイムスタンプまたは Date を使用して setSessionId を呼び出します。負以外のタイムスタンプは、その時点で新しいセッションを開始し、負のタイムスタンプは現在のセッションを終了します。

// Start a new session at the current time.
amplitude.setSessionId(timestamp: Int64(Date().timeIntervalSince1970 * 1000))
// Or pass a Date directly.
amplitude.setSessionId(date: Date())

ログレベル

開発者コンソールに出力されるログのレベルを制御します。

• 「OFF」：すべてのログメッセージを抑制します。
• 「ERROR」：エラーメッセージのみを表示します。
• 「WARN」：エラーメッセージと警告を表示します。 このレベルでは、問題となり、データに奇妙な点が発生する可能性がある問題が記録されます。 たとえば、このレベルでは、値が NULL であるプロパティに対して警告が表示されます。
• 「ログ」：イベントに関する情報メッセージを表示します。
• 「DEBUG」：デバッグに役立つ可能性のあるエラーメッセージ、警告、および情報メッセージを表示します。

ログレベルを希望のレベルlogLevelに設定します。

let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: AMPLITUDE_API_KEY,
        logLevel: LogLevelEnum.log
    )
)

Amplitudeはユーザーデータを統合するため、既知のuserIdまたはdeviceIdに関連付けられたイベントは、既存のユーザーに紐付けられます。 ユーザーがログアウトした場合、Amplitudeはそのユーザーのログアウトイベントをユーザーの記録とマージできます。 この動作を変更して、代わりに匿名ユーザーにこれらのイベントを記録することができます。

匿名ユーザーにイベントをログに記録するには：

1. userIdをnullに設定します。
2. 新しいdeviceIdを生成します。

現在のユーザーまたはデバイスからのイベントは、Amplitudeで新しいユーザーとして表示されます。 注：これを行うと、2人のユーザーが同じデバイスを使用していたことが確認できなくなります。

amplitude.reset()

追跡を無効にする

デフォルトでは、iOS SDKはcarrier、city、country、ip_address、language、platformなどのいくつかのユーザープロパティを追跡します。

付属のTrackingOptionsインターフェースを使用して、個々のフィールドをカスタマイズしたり、表示・非表示を切り替えたりしてください。 apiKeyを使用してSDKを初期化する前に、設定に基づいてTrackingOptionsインスタンスを作成し、それをSDKインスタンスに設定してください。

let trackingOptions = TrackingOptions()
trackingOptions.disableTrackCity().disableTrackIpAddress()
let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: AMPLITUDE_API_KEY,
        trackingOptions: trackingOptions
    )
)

各フィールドの追跡設定を個別に制御することができ、それぞれに対応するメソッドがあります（例：disableCountry、disableLanguage)。

キャリア

Amplitudeは、CTTelephonyNetworkInfoを使用してユーザーのモバイルキャリアを決定します。この場合、simの登録済みオペレーターが返されます。

COPPA制御

IDFA、IDFV、都市、IPアドレス、および位置情報の追跡に関するCOPPA (児童オンラインプライバシー保護法) の制限を一度に有効または無効にできます。13 歳未満の子供から情報を求めるアプリは、COPPA に準拠する必要があります。

let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: AMPLITUDE_API_KEY,
        enableCoppaControl: true
    )
)

広告主ID

広告主 ID（IDFA とも呼ばれます）は、iOS および Google Play ストアによって提供される固有の識別子です。 この情報はユーザーのデバイスだけでなく、すべての人に固有のものであるため、モバイル アトリビューションに役立ちます。

モバイルアトリビューションとは、モバイルアプリのインストールが、いずれの元ソース（例：広告キャンペーンやアプリストアの検索など）に起因するかを特定することです。 モバイルアプリはIDFAを要求するには権限を必要とし、子供をターゲットにしたアプリはまったく追跡できません。IDFAが利用できない場合は、IDFVやデバイスID、または電子メールログインシステムの使用を検討してください。

IDFAを取得して追跡イベントに追加するには、このサンプルプラグインを参考にして、独自のプラグインを実装してください。

デバイスIDのライフサイクル

SDKはデバイスIDを次の順序で初期化し、デバイスIDを最初に検出された有効な値に設定します。

1. AmplitudeインスタンスのデバイスID（setDeviceId()で設定した場合）。
2. IDFV が存在する場合。
3. ランダムに生成されたUUID文字列。

1人のユーザーが複数のデバイスを使用

1人のユーザーが複数のデバイスを所有することができ、それぞれに異なるデバイスIDがあります。一貫性を保つために、これらのすべてのデバイスで一貫したユーザーIDを設定してください。デバイスIDは異なっていても、Amplitudeはそれらを単一のAmplitudeIDにマージし、それらをユニークなユーザーとして識別することができます。

新しいデバイスへの転送

ユーザーが新しいデバイスに切り替えると、複数のデバイスに同じデバイスIDが割り当てられる場合があります。ユーザーが新しいデバイスに移行するとき、ユーザーは多くの場合、他の関連データと一緒にアプリケーションを移行します。 転送される特定のコンテンツはアプリケーションによって異なる場合があります。 一般的に、ITにはアプリケーションに関連付けられたデータベースとファイルディレクトリが含まれます。ただし、含まれている正確なアイテムは、アプリのデザインと開発者が行った選択によって異なります。 ユーザーがデータベースやファイルディレクトリをあるデバイスから別のデバイスにバックアップした場合でも、その中に保存されているデバイスIDは依然として存在している可能性があります。その結果、SDKが初期化中にITを取得した場合、異なるデバイスが同じデバイスIDを使用することになる可能性があります。

デバイスIDを取得する

ヘルパーメソッドgetDeviceId()を使用して、現在のdeviceIdの値を取得します。

let deviceId = amplitude.getDeviceId()

デバイスを設定する方法については、カスタムデバイスIDを参照してください。

位置情報追跡

AmplitudeはデフォルトでユーザーイベントのIPを場所に変換します（GeoIP検索）。 アプリ独自の追跡ソリューションまたはユーザーデータがこの情報を上書きする場合があります。

ユーザーを追跡から除外する

ユーザーはトラッキングを完全にオプトアウトしたい場合があります。つまり、Amplitudeはユーザーのイベントや閲覧履歴を一切トラッキングしません。OptOutは、ユーザーのプライバシー保護要求に応える方法を提供します。

let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: AMPLITUDE_API_KEY,
        optOut: true
    )
)

ログコールバックを設定する

LoggerProviderからカスタマイズされたloggerProviderクラスを実装し、初期化時に設定にそれを渡すことで、実稼働環境でSDKからエラーメッセージを収集できます。

class SampleLogger: Logger {
    typealias LogLevel = LogLevelEnum
    var logLevel: Int
    init(logLevel: Int = LogLevelEnum.off.rawValue) {
        self.logLevel = logLevel
    }
    func error(message: String) {
        // TODO: handle error message
    }
    func warn(message: String) {
        // TODO: handle warn message
    }
    func log(message: String) {
        // TODO: handle log message
    }
    func debug(message: String) {
        // TODO: handle debug message
    }
}
let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: AMPLITUDE_API_KEY,
        loggerProvider: SampleLogger()
    )
)

セキュリティー

iOS は、各アプリケーションのデータを独自のセキュアなディレクトリに保存することで、アプリケーションデータを自動的に保護します。 通常、他のアプリケーションはこのディレクトリにアクセスできません。 ただし、デバイスがジェイルブレイクされた場合、アプリはデバイス上のすべてのディレクトリに root アクセス権を取得します。

他のアプリがジェイルブレイクされたデバイス上のアプリのAmplitudeデータにアクセスすることを防ぐために、AmplitudeはSDKに固有のインスタンス名を設定することをお勧めします。 これにより、他のアプリから分離された固有のデータベースが作成されます。

let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: "API-KEY",
        instanceName: "my-unique-instance-name"
    )
)

オフラインモード

バージョン1.3.0以降、Amplitude iOS Swift SDKはオフラインモードをサポートしています。 SDK はイベントを追跡するたびにネットワーク接続を確認します。 デバイスがネットワーク接続されている場合、SDKはフラッシュをスケジュールします。そうでない場合、SDKはイベントをストレージに保存します。また、SDKはネットワーク接続の変更を監視し、デバイスが再接続されたときに保存されているすべてのイベントをフラッシュします。

オフラインモードを無効にするには、初期化時に offline: NetworkConnectivityCheckerPlugin.Disabled を追加します。

let amplitude = Amplitude(
    configuration: Configuration(
        apiKey: "API-KEY",
        offline: NetworkConnectivityCheckerPlugin.Disabled
    )
)

独自のオフラインロジックを実装することもできます：

1. 上記のようにデフォルトのオフラインロジックを無効にします。
2. amplitude.configuration.offlineをご自身で切り替えてください。

Appleプライバシーマニフェスト

2020年12月8日より、Appleはすべての新規アプリおよびアプリのアップデートに対して、プライバシーマニフェストファイルの提出を義務付けています。 Appleは2024年春にこれを義務化する予定です。 Amplitudeはアプリのサードパーティであるため、Amplitudeをユーザーのデータとともにどのように使用しているかをユーザーに適切に開示する必要があります。

NSPrivacyTracking

デフォルトでは、Amplitudeはトラッキングにデータを使用しません。 このフィールドを追加し、アプリで対応している場合はそれをtrueに設定してください。

NSPrivacyCollectedDataTypes

デフォルトでは、SDKはdeviceIdのみを追跡します。 setUserId()はuserIdの追跡にも使用できます。 これを行うには、「ユーザーID」データ型を追加します。データの種類に関する詳細は、Appleの記事「プライバシーマニフェストにおけるデータの使用について説明する」を参照してください。

NSPrivacyTrackingDomains

NSPrivacyTrackingをtrueに設定した場合、設定に基づいてNSPrivacyTrackingDomainsに少なくとも1つのインターネットドメインを指定してください。

NSPrivacyAccessedAPITypes

このSDKでは、IDの保存にuserDefaultsAPIのみを使用しています。

アプリのプライバシーレポートを作成する

アプリのプライバシーを作成する方法に関する手順に従ってください。