iOS migration from Appboy 4.7.0 to Braze Swift SDK

Question

Hi everyone 👋

We’re investigating how to migrate a production iOS app safely from the legacy braze-ios-sdk / Appboy 4.7.0 SDK to the current Braze Swift SDK. We use Swift Package Manager.

Our existing integration covers customer identification, sessions, custom events, user attributes, Content Cards, in-app messages, push notifications and deep links. Our aim is to preserve existing customer profiles and behaviour while moving onto a supported SDK.

We have reviewed the Appboy-to-Braze migration guide, but would appreciate current guidance on the following areas—ideally from a Braze team member where these relate to official support.

1. Supported migration route and target version

* Is a direct migration from Appboy 4.7.0 to the current 17.x SDK supported?
* Is an intermediate version required or recommended?
* If an intermediate migration is appropriate, what is the oldest Swift SDK line still eligible for production support, critical fixes and security guidance?
* Should a new production migration currently target 17.0.0 or a later 17.x patch?

2. Compatibility libraries

* Are BrazeKitCompat and BrazeUICompat supported for new production migrations on the current 17.x line?
* If so, is there a published support or removal horizon for those libraries?
* Are there important limitations to consider when using them as a temporary migration stage?

We understand that switching to the modern Braze(configuration:) initialisation disables the compatibility APIs, so we would keep those stages separate.

3. Consent-aware initialisation

Our app may need to wait until the applicable consent state is known before starting the SDK. This is a technical lifecycle question rather than a request for legal or consent-policy advice.

* Can the compatibility Appboy.start(...) initialisation APIs safely be called later in the application lifecycle instead of at launch?
* Are there minimum SDK versions or limitations affecting in-app messages, Content Cards, push handling or deep links when initialisation is delayed?

4. Swift Package Manager and UI resources

A previous migration attempt to Braze Swift SDK 14.1.0 was reverted after an in-app message caused a runtime crash because braze-swift-sdk_BrazeUI.bundle could not be found.

The missing bundle is confirmed, although we have not proven the precise build-system cause. Our package products now link directly to the application target, and we are separately testing the contents of a representative Release archive.

* Are there known Swift Package Manager resource-embedding requirements or issues for BrazeUI or BrazeUICompatwhen linked directly to an app target?
* Are there particular SDK versions, Xcode settings or archive contents we should check?

5. Customer identity and profile continuity

The legacy integration uses the SDK’s IDFV-based device identity and calls changeUser when customers authenticate. We have separate UK and Ireland authentication paths.

* What validation does Braze recommend to confirm that existing customer profiles, device associations and push tokens are preserved during this migration?
* Are there specific precautions for preventing duplicate profiles or incorrect associations when customers re-identify through separate market-specific authentication paths?

Links to current documentation, known issues or support-lifecycle information would be very helpful. I’m also happy to split this into smaller questions if that would make it easier to answer.

Thanks very much for any guidance!

stefanie.baldwin · Answer

HI @gousto_chris

We're so glad you got great deets from Operator, but wanted to make sure we caught up with you here too (also for other folks who may have similar questions in future)

Forgive me as these responses are not my own- I've connected with a few colleagues here at Braze to help put these together.

Please don't be shy if you have additional questions.

Glad you're here, and grateful for your questions

1. Supported migration route and target version1. Appboy iOS SDK 4.7.0

AppboyKit is end-of-life. Messaging and analytics should continue to function, but it no longer receives new features, bug fixes, security updates, or technical support. From a security and support perspective, we recommend migrating off version 4.7.0.

2. Minimum Swift SDK version for production support

We do not publish a specific minimum Swift SDK version for production support or critical fixes. The Swift SDK is a Tier 1 SDK, and we recommend using the latest stable release.

Relevant docs:

* Appboy-to-Braze Swift SDK migration guide
* SDK version management & deprecation policy
* Swift SDK repository guide (version support / requirements)
* Braze Swift SDK changelog (GitHub)

2. Compatibility libraries (BrazeKitCompat / BrazeUICompat)3. BrazeKitCompat and BrazeUICompat on 17.x

These packages remain available for production migrations and are intended to reduce migration effort from AppboyKit. They are a transition path rather than a long-term destination, so we recommend planning a future migration to the native BrazeKit and BrazeUI APIs.

4. Compat-library sunset timeline

We plan to sunset BrazeKitCompat, but there is no published removal date or timeline at this time.

3. Consent-aware (delayed) initialization5. Delayed initialization after consent

Yes. Call Braze.prepareForDelayedInitialization() early in didFinishLaunchingWithOptions, then initialize Braze after consent using Appboy.start(...) or Braze(configuration:). This is the documented approach for delayed initialization, including compat-layer integrations.

6. Behavior before initialization

Channel or eventBehavior before initializationPush tokensQueued and processed after initializationPush opens and analyticsQueued by default, with configurable drop behaviorDeep linksQueued and processed after initializationIn-app messagesNot buffered; the SDK must be initialized to receive themContent CardsNot buffered; the SDK syncs available cards after initialization

The key consideration is that in-app messages and Content Cards are not guaranteed to be available before the SDK initializes.

7. Minimum SDK version for delayed initialization

Delayed initialization requires Swift SDK version 11.2.0 or later. Version 14.1.0 added further push and deep-link improvements, so version 17.x is well above both thresholds.

Relevant docs:

* Integrate the Braze SDK — Set up delayed initialization

4. Swift Package Manager and UI resources8. Missing braze-swift-sdk_BrazeUI.bundle runtime error

This is not documented as a known SDK issue. On 17.x, it is more likely an integration or build-configuration issue than an SDK defect.

9. SPM, Xcode, and archive requirements

Starting with Swift SDK 12.0.0, select Embed & Sign for Braze XCFrameworks, for both static and dynamic variants. This ensures framework resources are embedded correctly and is the first item to verify for a missing-resource error during archive or release builds.

10. Resource-bundle override APIs

The supported APIs are BrazeKit.overrideResourcesBundle and BrazeUI.overrideResourcesBundle. These are intended for non-standard build systems or resource-loading setups.

Relevant docs:

* Integrate the Braze SDK (SPM setup, framework/library reference)
* Braze Swift SDK changelog — 12.0.0 resource/Embed & Sign change

5. Customer identity and profile continuity11. Migration validation

We do not publish a dedicated migration checklist for preserving profiles, device associations, and push tokens. We recommend validating the following before a broad rollout:

* Confirm push-token registration or push automation remains configured.
* Compare push-registered user counts before and after rollout.
* Spot-check known external_id values to confirm their device associations.
* Test push delivery and in-app messaging on migrated builds.

12. changeUser and push-token association

We do not publish an explicit guarantee for push-token reassociation after changeUser. The intended behavior is for the device token to be associated with the newly identified user. Before a full rollout, test this flow with representative users and confirm the token appears on the new profile in the dashboard.

Relevant docs:

* Set user IDs through the Braze SDK (changeUser, merge behavior, best practices)
* Appboy-to-Braze Swift SDK migration guide (re-identify users step)

gousto_chris · Answer

I think I got what I need from BrazeAI Operator™! Well done, Braze; you created an actually helpful support 'bot'! 🤩