iOS SDKでカスタム要素を表示する

カスタム要素を含む画面が開くと、Adapty SDKは要素のTypeとIDをアプリコード内のリゾルバーに渡します。リゾルバーは以下のいずれかを返します。

  • TypeとIDが一致するビュー: ユーザーには、Lottieアニメーション、インタラクティブなチャート、カメラプレビューなど、ネイティブのSwiftUIビューが表示されます。
  • ビューなし: ユーザーにはフォールバックが表示されます。これは、フローおよびペイウォールビルダーのカスタム要素内のコンテンツです。

ユーザーが古いバージョンのアプリを使用している場合(リゾルバーがまったく存在しないバージョン)でも、フォールバックコンテンツが表示されます。そのため、アプリをリリースする前にフローを公開することができます。

始める前に

必要なもの:

  • Adapty iOS SDK 4.4以降: それ以前のバージョンでは、すべてのカスタム要素にフォールバックが表示されます。
  • ネイティブiOSアプリ: Flutter などのクロスプラットフォームフレームワーク向け Adapty SDK では、すべてのカスタム要素にフォールバックが表示されます。
  • カスタム要素の命名規則: 各ネイティブビューに lottie_animation のような Type を付けてください。Type には小文字、数字、アンダースコアのみ使用できます。同じ Type のカスタム要素を区別するには、welcome_wave のような ID を各要素に付けます。コード内の Type と ID は、フロー&ペイウォールビルダーで設定したものと一致している必要があります。

カスタム要素のビューを作成する

各 Type に対して、ネイティブの SwiftUI ビューを新規作成するか、アプリ内の既存ビューを再利用してください。以下は lottie_animation Type の Lottie アニメーションを再生するビューの例です:


struct LottieElementView: View {
    let animation: LottieAnimation?

    var body: some View {
        LottieView(animation: animation)
            .resizable()
            .looping()
    }
}

要件とベストプラクティスの確認

  • サイズ設定:
    • パディングと配置: ネイティブビューが、フロー&ペイウォールビルダーで確保したコンテナにパディングを引いたサイズで収まるようにしてください。ビューがエリア全体を占有しない場合、デフォルトではそのエリアの左上隅に表示されます。位置を変更するには、カスタム要素の Layout セクションで配置を調整してください。
    • Hug の高さ: カスタム要素の高さが Hug に設定されている場合、利用可能なスペースいっぱいに広がるビュー(マップなど)は縮んで表示されます。代わりにカスタム要素にFixed の高さを設定してください。
  • フローアクション: ネイティブビューからは、次の画面への遷移などのフローアクションをトリガーできません。ナビゲーションボタン、購入ボタン、その他フローアクションを持つボタンはカスタム要素の外に配置してください。
  • 選択可能な要素: カスタム要素をプロダクトカードや他の選択可能な要素の外に配置してください。選択状態が変わると、ネイティブビューの状態が失われることがあります。
  • ナビゲーションの処理: ユーザーが次の画面に移動すると、SwiftUI はネイティブビューの onDisappear アクションを実行します。このアクション内で、カメラセッション、プレーヤー、位置情報の更新など、ビューが開始したものを停止してください。非同期処理には .task を使用してください。ビューが非表示になると SwiftUI がキャンセルします。ユーザーが戻ってきたとき、SDK は再びリゾルバーを呼び出し、SwiftUI はビューの状態をリセットします。
  • UIKit ビュー: UIViewRepresentable でラップしてください。

カスタム要素とビューを照合するリゾルバを作成する

リゾルバを作成するには、型を AdaptyUICustomElementsResolver プロトコルに準拠させ、view(forType:id:context:) メソッドを実装します。

lottie_animation タイプに対して、次のリゾルバは LottieElementView を返します。ID はアプリバンドル内のアニメーションファイル名(例:welcome_wave)を指定します。


struct CustomElementsResolver: AdaptyUICustomElementsResolver {
    func view(
        forType type: String,
        id: String,
        context: AdaptyUICustomElementContext
    ) -> AnyView? {
        switch type {
        case "lottie_animation":
            // the ID names the animation file, such as welcome_wave.json
            guard let animation = LottieAnimation.named(id) else {
                return nil // no file for this ID: show the fallback
            }
            return AnyView(LottieElementView(animation: animation))
        default:
            return nil
        }
    }
}

default ケースでは nil を返します。アプリのリリース後に新しいTypeのカスタム要素を追加した場合、リリース済みバージョンのユーザーにはフォールバックが表示されます。

リゾルバーには以下の要件があります。

  • ネットワークデータとプレイヤー: ネットワークデータとプレイヤーは、リゾルバーではなくネイティブビューのステートに保持してください。SDKは、プロダクトの読み込みや購入開始時など、画面が開いている間にリゾルバーを何度も呼び出します。リゾルバー内のコードは呼び出しのたびに再実行されるため、ネットワークリクエストが繰り返され、プレイヤーが最初からやり直しになります。SwiftUIは呼び出し間でネイティブビューのステートを保持するため、データは一度だけ読み込まれ、プレイヤーは再生を続けられます。プレイヤー、セッション、ネットワークリクエストは、@Stateプロパティの初期値ではなく、.taskや@StateObjectの中で作成してください。Swiftはリゾルバーがビューを作成するたびにその初期値を再評価します。
  • カスタム要素ごとに1つのネイティブビュー: 一部のネイティブビューは、データの読み込み時やユーザーのタップ時など、画面が開いている間に変化します。このロジックはリゾルバーではなく、ビューのbody自体に実装してください。同じカスタム要素に対してリゾルバーが異なるビューを返すと、SwiftUIはそのビューのステートをリセットします。
  • アプリデータ: データを保持するアプリオブジェクト(例:デイリーストリークを持つObservableObject)は、リゾルバーのプロパティに格納してください。そのオブジェクトをネイティブビューに渡し、ビューでは@ObservedObjectを使って監視します。ストリーク数のようにリゾルバーにコピーした値は、リゾルバーを作成した時点の値のまま変わりません。このデータには環境オブジェクトを使わないでください。UIKitのフローコントローラーでは、ネイティブビューはアプリのSwiftUI環境を受け取りません。

フォールバックコンテンツの条件を設定する

ユーザーに空のカスタム要素ではなくフォールバックコンテンツを表示するには、以下の状況で nil を返してください:

  • 表示するものがない — 必要なアニメーションファイルまたはデータファイルが存在しない。
  • 処理するものがない — ユーザーがクイズの質問をスキップし、データが不完全である。
  • アクセスが禁止されている — 権限が拒否されたため、ビューがリソースにアクセスできない。

たとえば、リゾルバーのguard文は、アニメーションファイルが見つからない場合にnilを返します。

パーミッションについては、スクリーンが開く前にユーザーが拒否した場合のみ nil を返してください。ユーザーがまだパーミッションリクエストに回答していない場合は、nil ではなくネイティブビューを返し、その中でパーミッションをリクエストしてください。たとえば、フローのマップにカスタム要素を表示するでは、iOS はマップが表示されたときに位置情報アクセスのプロンプトを表示します。ネイティブビューは、ユーザーがアクセスを許可した直後にマップを表示できます。ユーザーが回答する前に nil を返すと、SDK が再びリゾルバーを呼び出すまで、許可後もフォールバックが表示されたままになります。

リゾルバーをSDKに渡す

まずはアプリ全体のリゾルバーを設定しましょう。SDKは、個別のリゾルバーを持たないすべてのフローでこれを呼び出します。アプリをリリースしなくても、新しいフローやA/Bテストでユーザーがネイティブビューを見られるようになります。これらのビューはデイリーストリークなど、アプリからデータを読み込むため、各ユーザー固有のデータを表示できます。

フローを開く際にアプリが初めてデータを取得できる場合は、そのフローにリゾルバーをアタッチします。たとえば、ペイウォールにユーザーが以前のフローで入力した体重を表示したり、ユーザーがエクスポートしようとしているドキュメントをプレビューしたりする場合がこれにあたります。また、そのフロー内の Type に対して別のビューを表示するために、1 つのフローにリゾルバーをアタッチすることもできます。

アプリ全体にリゾルバーを設定する

すべてのフローでリゾルバーを使用するには、アプリ起動時などに AdaptyUI.setCustomElementsResolver(_:) を一度呼び出します。


// keep this instance: a resolver for one flow can reuse it
@MainActor let customElementsResolver = CustomElementsResolver()

AdaptyUI.setCustomElementsResolver(customElementsResolver)
Tip

リゾルバーアプローチのよりシンプルで機能が限定された代替手段として、Type キーを持つ [String: AdaptyUICustomElementBuilder] ディクショナリを渡す方法があります。コード量は少なくて済みますが、フォールバックコンテンツの条件設定はできません。

AdaptyUI.setCustomElementsResolver([
    "lottie_animation": .init { _, id, _ in LottieElementView(animation: .named(id)) },
])

1つのフローにリゾルバーを紐付ける

フローに紐付けたリゾルバーは、そのフロー内でアプリ全体のリゾルバーを上書きします。このリゾルバーに渡した値は、フロー設定を取得したときの値のまま保持されます。新しい値を表示するには、設定を再取得してください。

このフロー内でアプリ全体のビューを維持するには、アプリ全体のリゾルバーをこのリゾルバーに渡し、他のタイプやIDに対してはアプリ全体のリゾルバーを呼び出してください。次のリゾルバーは、ユーザーがエクスポートしようとしているドキュメントをプレビューし、その他すべてのカスタム要素に対してアプリ全体のリゾルバーを呼び出します。


struct ExportPaywallResolver: AdaptyUICustomElementsResolver {
    let document: Document // the document that the user wants to export
    let appWideResolver: any AdaptyUICustomElementsResolver

    func view(
        forType type: String,
        id: String,
        context: AdaptyUICustomElementContext
    ) -> AnyView? {
        if type == "document_preview" {
            return AnyView(DocumentPreview(document: document))
        }
        // other Types: the views of the app-wide resolver
        return appWideResolver.view(forType: type, id: id, context: context)
    }
}

フローの設定を取得する際に、リゾルバをフローにアタッチします:

func showExportPaywall(flow: AdaptyFlow, document: Document) async {
    do {
        let flowConfiguration = try await AdaptyUI.getFlowConfiguration(
            forFlow: flow,
            customElementsResolver: ExportPaywallResolver(
                document: document,
                appWideResolver: customElementsResolver // the instance that you set app-wide
            )
        )
        // present the flow
    } catch {
        // handle the error
    }
}

ディクショナリをリゾルバの代わりに使用する場合は、2つのディクショナリをマージし、その結果をフローにアタッチします: appWideViews.merging(flowViews) { _, flowView in flowView }。両方のディクショナリに同じ型が存在する場合、このコードはそのフロー用のビューを保持します。

デバイスでテストする

フローおよびペイウォールビルダーはアプリのコードを実行できないため、キャンバスにはフォールバックのみが表示されます。ネイティブビューにエラーがあると、アプリがクラッシュする可能性があります。アプリをリリースする前に、カスタム要素を含むすべての画面をデバイスでテストしてください。

  1. 各フローの最新の公開バージョンをキャッシュ済みのバージョンではなく表示するには、デバイスをテストデバイスとして登録してください。

  2. デバイス上で、リゾルバーを含むビルドを実行します。カスタム要素があるすべての画面を開き、ネイティブビューが表示されてカスタム要素に収まっていることを確認してください。ビューがスクロールやドラッグに対応している場合は、これらのジェスチャーもテストしてください。

  3. ネイティブビューの代わりにフォールバックが表示される場合は、Xcode コンソールで custom element <type>:<id> is not served by a resolver という警告を探してください。その上で、以下を確認してください。

    • 警告内の Type と ID が、コード内のものと一字一句一致しているか。
    • アプリが、ビューに必要なファイル、データ、または権限を持っているか。
    • カスタム要素を含む画面が開く前に、アプリ全体のリゾルバーが設定されているか。
    • このフロー用のリゾルバー(アタッチしている場合)が、その Type と ID に対応するビューを返しているか。

    もし警告が表示されない場合は、アプリが Adapty iOS SDK 4.4 以降を使用していること、および Adapty.logLevel が .error に設定されていないことを確認してください。

  4. フォールバックをプレビューするには、Type に nil を返し、画面を再度開いてください。

使用例

各レシピには、ビルダーでの設定とアプリのコードが含まれています: