Overview

The Recurly Engage Apple SDK provides native support for iOS and tvOS apps, automatically handling modal, banner, video popups, and inline prompt rendering, as well as tracking user-triggered events.

Key benefits

• SDK integration: Seamlessly embed prompts and track user events in native iOS and tvOS applications.
• Automatic UI handling: Built-in support for modals, banners, and inline prompts without manual UI code.
• Deep linking & metadata: Leverage custom metadata and deep links for tailored in-app navigation.

Key details

The Recurly Engage Apple SDK brings the ability to monitor consumption and show configured prompts within your native iOS and tvOS apps. The SDK automatically handles display of modals (popups, video popups, and banners) and the related user-triggered events. Inline prompts are accessible via helper functions with the necessary metadata for rendering in chosen areas of the app.

Install the SDK

The Recurly Engage Apple SDK includes support for iOS and tvOS. The latest SDK version and example app source code are available here. Contact your Customer Success Manager for access keys to run the example.

Swift Package Manager

You may add the SDK from the public GitHub repository.

Steps:

1. Add a new Package Dependency to your existing project.

2. Paste the GitHub repo URL and select an appropriate Dependency Rule. Add to your project.

3. Complete adding the package.

4. Confirm successful package installation.

Legacy installation via local SDK

Steps:

1. In Xcode, select Target > General > Frameworks, Libraries, and Embedded Content, then click +.

2. Choose Add Other > Add Files, and select the RecurlyEngage.xcframework.

3. Ensure the Embed & Sign option is selected.
4. Import the SDK into your project.

5. Initialize the SDK per instructions below.

Initialize Recurly Engage

In AppDelegate.swift, add to application(_:didFinishLaunchingWithOptions:)—replace with your AppID and UserID (found under Settings > Application in Pulse):

func application(
   _ application: UIApplication,
   didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
   PromotionManager.initPromotion(
     appId: "[Your AppID]",
     userId: "[Your UserID]"
   ) { result in
     // handle result
   }
   return true
}

## Trigger popup via screen name

Add inside your view controller’s `viewDidLoad()`:

```swift
override func viewDidLoad() {
    super.viewDidLoad()
    PromotionManager.setScreenName(self, "ViewController") { result in
        switch result.code {
        case .timerExpired, .declined, .abort, .accepted:
            // handle each case
            break
        default:
            break
        }
    }
}

Trigger popup via button click

Add in your button’s touchUpInside handler:

@IBAction func buttonClicked(_ sender: Any) {
    PromotionManager.buttonClick(self, "unsubscribe") { [weak self] result in
        switch result.code {
        case .accepted, .declined, .timerExpired, .abort:
            // handle each case
            break
        default:
            break
        }
    }
}

Retrieve inline prompts

Use async API to fetch inline prompts and report activities:

func fetchPrompts() async {
    if let prompt = PromotionManager
        .getTriggerablePrompts(screenName: "screenName", clickId: nil)
        .first 
    {
        // Access prompt properties
        try? await prompt.impression()
        try? await prompt.dismiss()
        // other events...
    }
}

Deep link and custom metadata

• Deep links and custom metadata added in Pulse are available in callbacks for setScreenName(), buttonClick(), and getTriggerablePrompts().
• Decode metadata using prompt.deviceMeta?.decodeValue(to: Meta.self).

Send Usage Tracking Event

Task {
    try? await PromotionManager.customTrack("[customTrackId]")
}

Update user ID

Change the user ID mid-session after authentication:

PromotionManager.setUserId("[New UserID]")

Debug view

Display the debug modal to reset or set a new user ID:

PromotionManager.showDebugView(self)