ガイドと調査 iOS SDK

AmplitudeのガイドとサーベイiOS SDKを使用すると、iOSアプリケーションにガイドとサーベイをデプロイできます。

インストールと検証

以下の手順に従ってSDKをインストールし、アプリをAmplitudeプロジェクトに接続し、ガイドやサーベイがアプリに届くことを確認してください。

要件

ガイドとサーベイiOS SDKには以下が必要です：

• iOS 15以降を搭載したユーザーデバイス。
• Swift 5.9以降。

ガイドとサーベイは、Amplitude Analyticsとは別に利用できます。

SDKのインストールと初期化

ガイドとサーベイは、既存のAmplitude実装環境（存在する場合）と最適に連携できるように、さまざまなインストールオプションをサポートしています。

Amplitude Analytics iOS SDK の使用

アプリがAmplitude Analytics iOS Swift SDKを使用している場合は、バージョン1.13.0以降を使用していることを確認してください。 次に、Swift Package ManagerまたはCocoaPodsを使用してガイドとサーベイiOS SDKをインストールします。

SDKの初期化

次に、必ずSDKを初期化してください。

import AmplitudeEngagementSwift
let API_KEY = "YOUR_API_KEY"
let configuration = Configuration(
  apiKey: API_KEY
)
let amplitude = Amplitude(configuration: configuration)
amplitude.add(
  plugin: AmplitudeEngagementPluginFactory.make(AmplitudeInitOptions())
)
// ----
// after calling `add`, the `engagement` SDK is available e.g. like this:
amplitude.engagement?.list()

このコールでは、Amplitude Analytics iOS SDKのプラグインシステムを使用して、ガイドとサーベイを既存のアナリティクス設定と統合します。プラグインを追加すると、アナリティクスとともにガイドとサーベイが初期化されます。ガイドとサーベイは同じ API キーとユーザー ID を共有しており、アナリティクスと直接通信します。 bootを個別に呼び出す必要はありません。

設定オプション

Amplitude Analytics Swift SDK 1.13.0+を使用していない場合

お使いのアプリがAmplitude Analytics iOS Swift SDK 1.13.0+を使用していない場合でも、ガイドとサーベイをインストールすることはできますが、アナリティクスSDKプラグインシステムを使用する代わりに.bootを直接呼び出す必要があります。

まず、Swift Package Manager または CocoaPods を使用してガイドとサーベイ iOS SDK をインストールします。

SDKの初期化

import AmplitudeEngagementSwift
let API_KEY = "YOUR_API_KEY"
let amplitudeEngagement = AmplitudeEngagementFactory.make(API_KEY)

設定オプション

SDKを起動する

// Basic boot with user ID
amplitudeEngagement.boot("USER_ID")
// Advanced boot with options
let bootOptions = AmplitudeBootOptions(
  user_id: "USER_ID",
  device_id: "DEVICE_ID",
  user_properties: ["key": "value"]
  integrations: [
    { event, eventProperties in
      // Custom event handler
    }
  ]
)
amplitudeEngagement.boot(options: bootOptions)

アプリケーションをプロジェクト設定に追加する

SDKをインストールした後、iOSアプリケーションをAmplitudeプロジェクト設定に追加して、ガイドやサーベイを作成するときにプラットフォームオプションとして表示されるようにしてください。

アプリケーションを追加するには：

1. Amplitudeの_設定 > プロジェクト_に移動します。
2. プロジェクトを選択します。
3. ガイドとサーベイタブに移動します。
4. App Management セクションを展開し、+ Add App をクリックします。
5. ドロップダウンから「iOS」を選択します。

アプリケーションを追加した後、iOSアプリユーザー向けのガイドやサーベイを作成または編集する際に、そのアプリケーションをプラットフォームオプションとして選択できます。

プレビューモードの設定と検証

ガイドやサーベイをアプリケーション内で直接プレビューすることで、ユーザーと同じ体験を確認できます。プレビュー機能を使用すると、コピー、ターゲット設定ルール、トリガーロジックの繰り返し調整が容易になり、インストールが正常に動作していることを確認できます。

モバイルURLスキームを特定する

URLスキームを特定するには：

1. Amplitudeの_設定 > プロジェクト_に移動します。
2. プロジェクトを選択します。
3. ［全般］タブに移動します。
4. **URLスキーム（モバイル）**フィールドを探します。
5. その値をコピーします（例：amp-abcdefgh12345678）。

XcodeでのURLスキームの追加

1. iOS プロジェクトを Xcode で開きます。
2. プロジェクトナビゲーター内で、アプリのターゲットを選択します。
3. [Info] タブで、[URL Types] セクションを見つけるか追加します。
4. 次の値を持つ新しい URL タイプを追加します。
   • URL識別子：AmplitudeURLSchemeなどの分かりやすい名前を入力します。
   • URLスキーム：Amplitudeからコピーした値を貼り付けます（例：amp-abc123）。

プレビューリンクの URL 処理を設定する

// In your AppDelegate or SceneDelegate
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
  if amplitudeEngagement.handleUrl(url) {
    return true
  }
  // Handle other URL schemes
  return false
}

QRコードスキャンによるインストールの確認

インストール作業がエンドツーエンドで行われていることを確認してください。

1. Amplitudeでガイドまたはサーベイを開き、プレビューをクリックします。
2. 表示されたQRコードをデバイスのカメラでスキャンするか、アプリがインストールされているデバイスでプレビューURLを開きます。
3. ガイドまたはサーベイがアプリ内で開くことを確認します。
4. 画面下部にある小さなAmplitudeロゴを探し、それをタップしてスーパーデバッガーを開きます。チェックする項目についてはスーパーデバッガーを参照してください。

アプリでプレビューが開かない場合や、ロゴが表示されない場合は、先に進む前に上記のURLスキーム設定手順を確認してください。

リファレンス

最小SDKバージョンを設定する（必要な場合）

SDKバージョン3.0.0以降でMinimum SDK versionをサポートしています。この設定は、古いSDKリリースで重大な問題を特定した場合の安全対策として使用してください。

SDK の最小バージョンを設定するには:

1. Amplitudeの_設定 > プロジェクト_に移動します。
2. プロジェクトを選択します。
3. ガイドとサーベイタブに移動します。
4. App Management セクションを展開し、+ Add App をクリックします。
5. ドロップダウンから「iOS」を選択します。
6. 「Minimum SDK version」に値を入力します。

この値を設定すると、ガイドとサーベイは設定済みの最小値と各アプリビルドのSDKバージョンを比較します。

• アプリのビルドで古いバージョンの SDK を使用している場合、SDK はそのビルドで初期化されません。
• アプリのビルドで同じバージョンまたは新しいバージョンの SDK を使用している場合、SDK は期待どおりに初期化されます。

この設定を使用すると、アプリケーションリリースをロールバックすることなく、問題のある既知のSDKバージョンに関するガイドやサーベイを停止できます。

最小SDKバージョンの使用例

アプリバージョン120ではGuides and Surveys SDK3.0.2を使用しており、アプリバージョン121ではバグ修正が含まれるGuides and Surveys SDK3.1.0を使用しているとします。最小SDKバージョンを3.1.0に設定すると次のようになります。

• アプリのバージョン120では、ガイドとサーベイが読み込まれなくなりました。
• アプリのバージョン121は引き続きガイドとサーベイを読み込みます。

インストールのトラブルシューティング

Swift パッケージマネージャーでのバージョンアップのトラブルシューティング

SDK バージョンをアップグレードしても予期しない動作が続く場合、Xcode は以前のバージョンのキャッシュ済みビルドアーティファクトを使用している可能性があります。 SPM キャッシュをクリアするには：

1. コマンドラインインターフェイス (ターミナルなど) またはファイル管理アプリ (Finder など) で、~/Library/Caches/org.swift.swiftpm/repositories に移動します。
2. Amplitude Engagement Swiftパッケージに関連するフォルダとロックファイルを削除します。
3. Xcode で File > Swift Packages > Reset Package Caches を実行します。
4. 次に、_File > Packages > Resolve Package Versions_を実行します。

問題が解決しない場合は、次の手順を実行してキャッシュ全体をリセットしてください。

rm -rf ~/Library/Caches/org.swift.swiftpm
rm -rf ~/Library/org.swift.swiftpm
rm -rf ~/Library/Developer/Xcode/DerivedData

CocoaPods インストールのトラブルシューティング

CocoaPodsでAmplitudeEngagementSwiftをインポートする際にエラーError extracting version from module interfaceが表示される場合、この問題は.swiftinterfaceファイルの改行コードが正しくないことが原因である可能性があります。core.autocrlf などの Git 設定では、これらのファイルの改行コードが LF から CRLF に書き換えられることがあります。

この問題を解決するには、プロジェクトルートにある.gitattributesファイルに次の行を追加してください。

*.swiftinterface text eol=lf
Pods/** -text

これらの行を追加したら、ビルドフォルダをクリーンアップしてプロジェクトを再構築してください。

画面追跡と要素ターゲティング

画面追跡と要素ターゲティングはオプションですが、ガイドやサーベイをよりターゲットに絞るのに役立ちます。

画面追跡を有効にする

画面ベースのターゲティングと画面表示時間トリガーについては、screenを呼び出してください。ガイドとサーベイでは、画面の文字列（たとえば「HomeScreen」）をガイドまたはサーベイページのターゲティングセクション内の文字列と比較します。

// Track screen views to trigger guides based on screens
amplitudeEngagement.screen("HomeScreen")

エレメントターゲティングを有効にする

ピン、ツールチップ、カード埋め込みガイドでは、SDKが画面上の特定の要素をターゲットにする必要があります。アプリでエレメントターゲティングを有効にするには、エレメントに一意の識別子を付与します。

// Swift UI
MySwiftView {
  // Content
}
.amplitudeView("MySwiftView", onTrigger: {
  // Optional code to run with tap element action
})
// UIKit: set an accessibility identifier so the SDK can target the view
let myView = MyUIKitView(...)
myView.accessibilityIdentifier = "MyView"
let tapGesture = UITapGestureRecognizer(target: self, action: #selector(myButtonAction))
myView.addGestureRecognizer(tapGesture)
myView.isUserInteractionEnabled = true
// Note: To use the tap element action from a guide or survey on your UIKit view,
// explicitly add a target to the view in addition to any gesture recognizers you may have added.
myView.addTarget(self, action: #selector(myButtonAction), for: .touchUpInside)
@objc func myButtonAction() {
  // Optional code to run on tap / tap element action
}

ローカリゼーション

ガイドやアンケートをローカライズするには、初期化時にlocaleオプションを設定します。 言語またはロケールを設定しない場合、Amplitudeはデフォルトの言語を使用します。

// Set locale during initialization
let configuration = Configuration(apiKey: API_KEY)
amplitude.add(
  plugin: AmplitudeEngagementPluginFactory.make(
    AmplitudeInitOptions(locale: "fr-FR")
  )
)

SDK の初期化後に言語を動的に更新するには、このupdateLanguageメソッドを使用します。 呼び出しを行うと、新しいロケールで設定がupdateLanguage再取得されます。

// Example: Update language to French with full locale
amplitudeEngagement.updateLanguage("fr-FR")
// Example: Update language to English with language code
amplitudeEngagement.updateLanguage("en")

その他のSDKメソッド

SDKを有効化および無効化する

disable()を使用して、ガイドやサーベイが一時的に表示されないようにしたり、現在表示されているものを非表示にしたりします。通常動作を再開するには、enable()を使用してください。

// Temporarily disable the SDK
amplitudeEngagement.disable()
// Re-enable the SDK
amplitudeEngagement.enable()

ターゲティングデータを更新する

refresh() を使用して、ユーザープロパティの更新後に Amplitude からターゲティング評価を再取得します。ガイドまたは調査が表示されている場合、SDKは更新をスキップします。

amplitudeEngagement.refresh()

自動更新間隔を設定する

ターゲット設定データの定期的な更新を有効にします。 これは、ブート後に呼び出して間隔を変更または無効にできます。有効な場合、最小間隔は60秒です。無効にするには、0 または負の値に設定します。

amplitudeEngagement.setAutoRefreshInterval(seconds: 3600) // Every hour
amplitudeEngagement.setAutoRefreshInterval(seconds: 0)    // Disable

テーマを管理

アプリケーションがライトモードとダークモードをサポートしている場合は、ビジュアルテーマモードを設定してください。

// Set the theme mode
amplitudeEngagement.setThemeMode(ThemeMode.DARK) // Options: AUTO, LIGHT, DARK

コールバックを登録する

ガイドまたはサーベイボタンの「コールバックを実行」アクションを設定して、コールバックを実行します。

engagement.addCallback(_ key: String, _ function: () -> Void)

engagement.addCallback("show-alert") {
  DispatchQueue.main.async {
    let alert = UIAlertController(
      title: "Callback",
      message: "Callback has been executed!",
      preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(title: "OK", style: .default))
    viewController.present(alert, animated: true)
  }
}

ルータの設定

ガイドとサーベイが画面ナビゲーションを処理する方法を設定します。

engagement.setRouter { identifier in
  // Your screen handling and navigation
}

ルーターを削除するには、unsetRouter() にお電話ください。

amplitudeEngagement.unsetRouter()

リセット

ガイドやサーベイを特定のステップにリセットできます。

amplitudeEngagement.reset(key: "GUIDE_KEY", stepIndex: 0)

List

すべてのライブガイドとサーベイのリストとそのステータスを取得できます。

let guidesAndSurveys = amplitudeEngagement.list()

表示する

特定のガイドやアンケートを表示します。画面ターゲット設定以外のターゲット設定ルールや制限を無視します。

amplitudeEngagement.show(key: "GUIDE_KEY")

イベントを転送する

Amplitude Analytics iOS SDK プラグインを使用していない場合（つまり、boot直接呼び出した場合）、forwardEventを使用してガイドとサーベイで_「イベント追跡時」_トリガーを有効にします。転送されたイベントはAmplitudeサーバーに送信されません。 SDK はこれらをローカル トリガー評価にのみ使用します。

amplitudeEngagement.forwardEvent([
  "event_type": "my event type",
  "event_properties": [String: String]()
])

スマートなインタラクションをリセットする

レイジタップ、ユーザーの非アクティブ状態、要素タップ検出など、スマートインタラクション検出器からキャッシュされた状態をすべてクリアするためにresetSmartInteractions()呼び出します。

amplitudeEngagement.resetSmartInteractions()

すべて閉じる

アクティブなすべてのガイドとサーベイを閉じます。

amplitudeEngagement.closeAll()

スーパーデバッガー

AmplitudeダッシュボードからプレビューQRコードをスキャンすると、画面下部に小さなAmplitudeロゴが表示されます。 これをタップすると、スーパーデバッガーパネルが開きます。

スーパーデバッガーには、詳細と設定という2つのタブがあります。

詳細タブ

_詳細_タブには、プレビューしているガイドまたはサーベイに関する情報が表示され、プレビューセッションの確認と制御を行うことができます。

ガイド / サーベイ：アクティブなガイドまたはサーベイの名前。タップすると、別のガイドやアンケートに切り替えることができます。

詳細:

• ステップ: 全ステップ数に対する現在のステップ番号 (たとえば、「1/3」)。コピーアイコンをタップして値をコピーします。
• ユーザー：プレビューセッションのユーザーID。コピーアイコンをタップしてコピーします。
• 画面：SDKが現在レポートしている画面名です。コピーアイコンをタップしてコピーします。

デバッグ: ガイドまたは調査が各条件チェックに合格したかどうかを示します。 各行が展開され、詳細が表示されます。

• 制限：ガイドまたはサーベイが表示制限に達したかどうか。展開して設定済みの制限を確認します。
• トリガー：ガイドまたは調査がトリガー条件を満たしているかどうか。展開すると、トリガータイプ、画面条件、ピンターゲット要素（該当する場合）を確認できます。
• スロットル：ガイドまたはサーベイがスロットル条件を満たしているかどうか。展開してスロットル設定を確認します。 <2>制限を無視する〼/2>をおんにすると、プレビューセッション中にスロットル制限を回避できます。

詳細設定：

• ピンのデバッグ：展開して、5秒ごとにピンの位置変更を有効にします。デバッガは定期的にピンの位置を再評価し、動的レイアウトでのピンの配置をデバッグするのに役立ちます。

パネルの下部：

• プレビューを再起動：ガイドまたは調査を最初のステップにリセットし、プレビューを再起動します。
• プレビューを閉じる: プレビュー モードを終了し、スーパー デバッガを閉じます。

設定タブ

_設定_タブには、現在のセッションのSDK設定と環境の詳細が表示されます。

SDK バージョン: アプリにインストールされている Engagement SDK のバージョンです。

インストール：

• タイプ：SDKのインストール方法（プラグインまたはスタンドアロンなど）。
• 構成：適用されるカスタム構成オプションの数とタイプ。

ユーザー:

• ユーザー ID: 起動時にSDKに渡されるユーザーIDです。
• プロパティ: 現在のセッションに設定されているすべてのユーザー プロパティ。

イベントフロー：イベントが正しく流れているかどうかを確認します：

• ガイドとサーベイSDKに流入するイベント: アナリティクスインスタンスからのイベントは、エンゲージメントSDKに到達します。
• Guides and Surveys SDKから送出されるイベント：Engagement SDKがイベントをAmplitudeに送信します。

サポート

**？**をタップします。_サポート_パネルを開くためのボタン。ここから次のことができます：

• SDKドキュメントやガイドとサーベイの概要へのリンクを開きます。
• バグレポートを提出する：デバッガーから直接バグレポートを送信できます。再現するステップ、予想される結果、実際の結果を入力してから、送信をタップします。

既知の制限事項

オフラインサポートなし

SDKは、ガイドやサーベイを取得して表示するためにアクティブなインターネット接続を必要とします。アプリが最初にロードされたときにデバイスがオフラインの場合、そのアプリセッションのガイドやサーベイは表示されません。

タブバー要素のターゲット設定

ピンやツールチップは、タブバーの項目（UITabBar要素など）をターゲットにすることはできません。タブバーは標準ビュー階層の外に存在するシステムレベルのコンポーネントを使用しているため、SDK はこれらの要素を確実に検索してガイドを添付できません。

アニメーション化された要素と移動するコンテナ内の要素をターゲットに設定する

ピンやツールチップは、次のようなビューや要素をターゲットにすることはできません。

• アニメーション化されているか、アニメーション化されたコンテナ内にあります（画面上を移動します）。
• ユーザーの操作に基づいて移動できるコンテナ内。

変更履歴

モバイルSDKの変更履歴にアクセスしてください。