Add in-app campaigns to iOS

In-app campaigns require BTXClientKit 3.3.0 or later and campaign access for your project. Check the changelog for release availability.

Add .inAppCampaigns to your existing configuration and identify the signed-in customer with a stable external ID. Include .helpCenter if campaign actions open Help Center articles; HTTPS actions do not require it. Keep any other capabilities your app already uses.

import BTXClientKit

BTX.configure(
    BTXConfiguration(
        publishableClientKey: "cfk_...",
        features: [.inAppCampaigns, .helpCenter]
    )
)
BTX.identify(BTXCustomer(externalID: currentUser.id))

After verifying the host app session and displaying its signed-in screen, signal readiness on the main actor:

// After verifying sign-in and displaying the host screen:
BTX.inAppCampaigns.setPresentationReady(true)

Readiness defaults to false on each launch. The SDK waits two seconds after readiness, then waits for a safe active window without a modal, keyboard, or another SDK presentation. Repeated true calls do not restart the delay.

Set readiness to false before a flow where campaign presentation would be inappropriate. This cancels pending presentation and dismisses visible content. Restore it only after the host is ready again. Before sign-out or account switching, also clear the identity:

// Before sign-out or account switching:
BTX.inAppCampaigns.setPresentationReady(false)
BTX.identify(nil)

Changing the customer or publishable client key resets readiness. Updating the same customer's profile does not. A credential refresh or return from the background does not select another campaign.

The SDK selects the customer's oldest active queued campaign when the app starts a new process. It attempts at most one presentation during that launch and requires an internet connection. Returning from the background does not trigger another campaign. Campaigns started after the app launches become eligible on a later launch.

Paused campaigns are skipped and keep their queue position when resumed. Content edits apply to pending deliveries. Content already reserved by the app for display stays unchanged. If an edit invalidates the app's pending content, presentation waits until a later launch.

Views, clicks, and dismissals are saved across restarts and sent when connectivity is available. An uncertain presentation is not repeated. A confirmed presentation failure can retry on a later launch. See the campaign guide for audience selection and delivery results.

Campaigns inherit messengerOptions.theme unless you provide BTXInAppCampaignOptions(theme:). Use the same BTXTheme as your other SDK surfaces:

BTX.configure(
    BTXConfiguration(
        publishableClientKey: "cfk_...",
        features: [.inAppCampaigns, .helpCenter],
        inAppCampaignOptions: BTXInAppCampaignOptions(theme: appTheme)
    )
)

Cards and banners use titleFont and bodyFont. Card actions use titleFont, primaryCTAColor, primaryCTATextColor, primaryCTAStrokeColor, and primaryCTAStyle. Register custom fonts in the host app before using them.

Banner bodies use at most two lines. The entire banner content opens its action; the close button only dismisses it. Artwork supports GIFs, pauses animation while inactive, and uses a still frame with Reduce Motion. Animations exceeding 120 frames or 64 MiB of decoded pixels use their first frame.

Run the app with a test customer and exercise the full path before shipping.

• Create a card and a banner for a segment containing only your test accounts.
• Confirm the campaign appears after sign-in and the readiness signal.
• Open the action destination, dismiss a campaign, and check the delivery results.
• Start the app again and confirm the same campaign does not repeat.
• Check sign-out, account switching, offline launch, and a screen that temporarily delays readiness.

If you enable campaign push, integrate push notifications and test on a physical device. Campaign push taps use the normal launch flow; they do not open Messenger, force old content, or execute the campaign action directly.