Get flows & paywalls - iOS

After you designed your flow or Paywall Builder paywall, you can display it in your mobile app. The first step is to get the flow or paywall associated with the placement and its view configuration as described below.

Fetch flow/paywall

If you’ve designed a flow or paywall using the Flow Builder or Paywall Builder, you don’t need to worry about rendering it in your mobile app code to display it to the user. Such a flow or paywall contains both what should be shown within it and how it should be shown. Nevertheless, you need to get its ID via the placement, its view configuration, and then present it in your mobile app.

To ensure optimal performance, it’s crucial to retrieve the flow or paywall and its view configuration as early as possible, allowing sufficient time for images to download before presenting them to the user.

To get a flow or paywall, use the getFlow method:

do {
    let flow = try await Adapty.getFlow(placementId: "YOUR_PLACEMENT_ID")
    // the requested flow/paywall
} catch {
    // handle the error
}

Adapty.getFlow(placementId: "YOUR_PLACEMENT_ID") { result in
    switch result {
        case let .success(flow):
            // the requested flow/paywall
        case let .failure(error):
            // handle the error
    }
}

Parameters:

Response parameters:

Fetch the view configuration

After fetching the flow or paywall, check whether it includes a view configuration via flow.hasViewConfiguration. The flag distinguishes how the placement was designed in the Adapty Dashboard:

• true — the placement was designed in the Flow Builder (a flow) or the Paywall Builder (a paywall). Adapty renders the UI for you. Continue with the steps below to fetch the view configuration and present the flow or paywall.
• false — the placement is a custom paywall with no Builder UI.

Use the getFlowConfiguration method to load the view configuration.

import AdaptyUI

guard flow.hasViewConfiguration else {
    // handle as remote config paywall
    return
}

let flowConfiguration = try await AdaptyUI.getFlowConfiguration(forFlow: flow)

Parameters:

Once loaded, present the flow/paywall.

Get a flow or paywall for a default audience to fetch it faster

Typically, flows and paywalls are fetched almost instantly, so you don’t need to worry about speeding up this process. However, in cases where you have numerous audiences and placements, and your users have a weak internet connection, fetching a flow or paywall may take longer than you’d like. In such situations, you might want to display a default flow or paywall to ensure a smooth user experience rather than showing nothing at all.

To address this, you can use the getFlowForDefaultAudience method, which fetches the flow or paywall of the specified placement for the All Users audience. However, it’s crucial to understand that the recommended approach is to fetch the flow or paywall by the getFlow method, as detailed in the Fetch Paywall Information section above.

Adapty.getFlowForDefaultAudience(placementId: "YOUR_PLACEMENT_ID") { result in
    switch result {
        case let .success(flow):
            // the requested flow
        case let .failure(error):
            // handle the error
    }
}

Customize assets

To customize images and videos in your paywall/flow, implement the custom assets.

Hero images and videos have predefined IDs: hero_image and hero_video. In a custom asset bundle, you target these elements by their IDs and customize their behavior.

For other images and videos, you need to set a custom ID in the Adapty dashboard.

For example, you can:

• Show a different image or video to some users.
• Show a local preview image while a remote main image is loading.
• Show a preview image before running a video.
• Provide a video’s pixel resolution so the player reserves layout space (aspect ratio = width / height) before the video loads. Pass nil to skip this.

Here’s an example of how you can provide custom assets via a simple dictionary:

let customAssets: [String: AdaptyCustomAsset] = [
    // Show a local image using a custom ID
    "custom_image": .image(
        .uiImage(value: UIImage(named: "image_name")!)
    ),

    // Show a local preview image while a remote main image is loading
    "hero_image": .image(
        .remote(
            url: URL(string: "https://example.com/image.jpg")!,
            preview: UIImage(named: "preview_image")
        )
    ),

    // Show a local video with a preview image and a known resolution
    "hero_video": .video(
        .file(
            url: Bundle.main.url(forResource: "custom_video", withExtension: "mp4")!,
            preview: .uiImage(value: UIImage(named: "video_preview")!),
            resolution: CGSize(width: 1080, height: 1920)
        )
    ),
]

let flowConfig = try await AdaptyUI.getFlowConfiguration(
    forFlow: flow,
    assetsResolver: customAssets
)

Set up developer-defined timers

To use custom timers in your mobile app, create an object that follows the AdaptyTimerResolver protocol. This object defines how each custom timer should be rendered. If you prefer, you can use a [String: Date] dictionary directly, as it already conforms to this protocol. Here is an example:

@MainActor
struct AdaptyTimerResolverImpl: AdaptyTimerResolver {
    func timerEndAtDate(for timerId: String) -> Date {
        switch timerId {
        case "CUSTOM_TIMER_6H":
            Date(timeIntervalSinceNow: 3600.0 * 6.0) // 6 hours
        case "CUSTOM_TIMER_NY":
            Calendar.current.date(from: DateComponents(year: 2025, month: 1, day: 1)) ?? Date(timeIntervalSinceNow: 3600.0)
        default:
            Date(timeIntervalSinceNow: 3600.0) // 1 hour
        }
    }
}

In this example, CUSTOM_TIMER_NY and CUSTOM_TIMER_6H are the Timer IDs of developer-defined timers you set in the Adapty Dashboard. The timerResolver ensures your app dynamically updates each timer with the correct value. For example:

• CUSTOM_TIMER_NY: The time remaining until the timer’s end, such as New Year’s Day.
• CUSTOM_TIMER_6H: The time left in a 6-hour period that started when the user opened the paywall.

After you designed the visual part for your paywall with the Paywall Builder in the Adapty Dashboard, you can display it in your mobile app. The first step is to get the paywall associated with the placement and its view configuration as described below.

Please be aware that this topic refers to Paywall Builder-customized paywalls. If you are implementing your paywalls manually, refer to Fetch paywalls and products for remote config paywalls.

Fetch paywall designed with Paywall Builder

If you’ve designed a paywall using the Paywall Builder, you don’t need to worry about rendering it in your mobile app code to display it to the user. Such a paywall contains both what should be shown within the paywall and how it should be shown. Nevertheless, you need to get its ID via the placement, its view configuration, and then present it in your mobile app.

To ensure optimal performance, it’s crucial to retrieve the paywall and its view configuration as early as possible, allowing sufficient time for images to download before presenting them to the user.

To get a paywall, use the getPaywall method:

do {
    let paywall = try await Adapty.getPaywall("YOUR_PLACEMENT_ID")
    // the requested paywall
} catch {
    // handle the error
}

Adapty.getPaywall(placementId: "YOUR_PLACEMENT_ID", locale: "en") { result in
    switch result {
        case let .success(paywall):
            // the requested paywall
        case let .failure(error):
            // handle the error
    }
}

Parameters:

Response parameters:

Fetch the view configuration of paywall designed using Paywall Builder

After fetching the paywall, check if it includes a view configuration, which indicates that it was created using Paywall Builder. This will guide you on how to display the paywall. If the view configuration is present, treat it as a Paywall Builder paywall; if not, handle it as a remote config paywall.

Use the getPaywallConfiguration method to load the view configuration.

import AdaptyUI

guard paywall.hasViewConfiguration else {
    //  use your custom logic
    return
}

do {
    let paywallConfiguration = try await AdaptyUI.getPaywallConfiguration(
            forPaywall: paywall,
            products: products
    )
    // use loaded configuration
} catch {
    // handle the error
}

Parameters:

Once loaded, present the paywall.

Get a paywall for a default audience to fetch it faster

Typically, paywalls are fetched almost instantly, so you don’t need to worry about speeding up this process. However, in cases where you have numerous audiences and paywalls, and your users have a weak internet connection, fetching a paywall may take longer than you’d like. In such situations, you might want to display a default paywall to ensure a smooth user experience rather than showing no paywall at all.

To address this, you can use the getPaywallForDefaultAudience method, which fetches the paywall of the specified placement for the All Users audience. However, it’s crucial to understand that the recommended approach is to fetch the paywall by the getPaywall method, as detailed in the Fetch Paywall Information section above.

Adapty.getPaywallForDefaultAudience(placementId: "YOUR_PLACEMENT_ID", locale: "en") { result in
    switch result {
        case let .success(paywall):
            // the requested paywall
        case let .failure(error):
            // handle the error
    }
}

Customize assets

To customize images and videos in your paywall, implement the custom assets.

Hero images and videos have predefined IDs: hero_image and hero_video. In a custom asset bundle, you target these elements by their IDs and customize their behavior.

For other images and videos, you need to set a custom ID in the Adapty dashboard.

For example, you can:

• Show a different image or video to some users.
• Show a local preview image while a remote main image is loading.
• Show a preview image before running a video.

Here’s an example of how you can provide custom assets via a simple dictionary:

let customAssets: [String: AdaptyCustomAsset] = [
    // Show a local image using a custom ID
    "custom_image": .image(
        .uiImage(value: UIImage(named: "image_name")!)
    ),

    // Show a local preview image while a remote main image is loading
    "hero_image": .image(
        .remote(
            url: URL(string: "https://example.com/image.jpg")!,
            preview: UIImage(named: "preview_image")
        )
    ),

    // Show a local video with a preview image
    "hero_video": .video(
        .file(
            url: Bundle.main.url(forResource: "custom_video", withExtension: "mp4")!,
            preview: .uiImage(value: UIImage(named: "video_preview")!)
        )
    ),
]

let paywallConfig = try await AdaptyUI.getPaywallConfiguration(
    forPaywall: paywall,
    assetsResolver: customAssets
)

Set up developer-defined timers

To use custom timers in your mobile app, create an object that follows the AdaptyTimerResolver protocol. This object defines how each custom timer should be rendered. If you prefer, you can use a [String: Date] dictionary directly, as it already conforms to this protocol. Here is an example:

@MainActor
struct AdaptyTimerResolverImpl: AdaptyTimerResolver {
    func timerEndAtDate(for timerId: String) -> Date {
        switch timerId {
        case "CUSTOM_TIMER_6H":
            Date(timeIntervalSinceNow: 3600.0 * 6.0) // 6 hours
        case "CUSTOM_TIMER_NY":
            Calendar.current.date(from: DateComponents(year: 2025, month: 1, day: 1)) ?? Date(timeIntervalSinceNow: 3600.0)
        default:
            Date(timeIntervalSinceNow: 3600.0) // 1 hour
        }
    }
}

In this example, CUSTOM_TIMER_NY and CUSTOM_TIMER_6H are the Timer IDs of developer-defined timers you set in the Adapty Dashboard. The timerResolver ensures your app dynamically updates each timer with the correct value. For example:

• CUSTOM_TIMER_NY: The time remaining until the timer’s end, such as New Year’s Day.
• CUSTOM_TIMER_6H: The time left in a 6-hour period that started when the user opened the paywall.