📘

iOS minimum version

The following steps assume you are targeting a minimum of iOS 12.0+. Marigold will not work on earlier versions of iOS.

Import the SDK into your project

There are four ways to integrate the Marigold SDK into your Xcode project:

• Swift Package Manager (from SDK version 12+)
• CocoaPods
• Carthage
• Manually.

Swift Package Manager Integration

1. If you're using Swift Package Manager, you can integrate the SDK by adding the iOS SDK repo URL as a package repository for your project.

📘

Extension SDK

If you're using the extension SDK you should add it to your main app target during the Swift Package Manager setup. You can then manually link it to your extension targets in the 'General' -> 'Frameworks and Libraries' settings.

CocoaPods Integration

1. If you're using CocoaPods, you can integrate the SDK simply by adding the following line to your Podfile:

pod 'Marigold'

# optional: add the extention SDK (should be added to main app target and any extension targets that require it)
pod 'Marigold-Extension'

2. Run pod install to install.

Carthage Integration

1. Install Carthage 0.17.0 or later.
2. Add github "sailthru/sailthru-mobile-ios-sdk" to your Cartfile.
3. Run carthage update
4. Drag Marigold.framework (and optionally the MarigoldExtension.framework) from the appropriate platform directory in Carthage/Build/iOS to the “Linked Frameworks and Libraries” section of your Xcode project’s “General” settings.
5. On your application targets’ “Build Phases” settings tab, click the “+” icon and choose “New Run Script Phase”. Create a Run Script with the following contents:
   /usr/local/bin/carthage copy-frameworks
6. Add the paths to the frameworks you want to use under “Input Files”, e.g.: $(SRCROOT)/Carthage/Build/iOS/Marigold.framework. This script works around an App Store submission bug triggered by universal binaries.

Manual Integration

If you don't use any of the dependency managers above, you can integrate the SDK manually.

1. Download the latest release of the SDK from Github and extract it.
2. Select Marigold.xcframework in Finder and drag and drop it into your Xcode project. Make sure “Copy items if needed” is selected, and click “Finish”
3. Add Marigold.xcframework to embedded binaries
4. To work-around this app store submission bug download the file on our Framework stripping page and place it in the root of your project. Note: this is only required below SDK version 12.0.0, XCFrameworks do not require this workaround.
5. In your target's build settings screen, build phases, add a new run script and enter bash $SRCROOT/strip-frameworks.sh in the text box.

📘

Upgrading the SDK

To upgrade to the latest version of the SDK, simply repeat the steps above. If you're using Cocoapods, simply run pod update Marigold which will use the latest version (unless you've specified a version in your Podfile). If you're using Carthage, use the update commands. Alternatively, download and drag in the updated Marigold.framework to your project. Swift Package Manager allows the version settings to be updates in the project settings under 'Swift Packages'.

Integrate the initialization code

Import the Marigold header file #import <Marigold/Marigold.h> into Objective-C files where you wish to call Marigold. For Swift applications, you'll need to add #import <Marigold/Marigold.h> to your bridging header.

#import <Marigold/Marigold.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    NSError *error;
    [[Marigold new] startEngine:SDK_KEY error:&error]; // Obtain SDK key from your Marigold app settings
    if (error) {
      // Handle error
    }
    return YES;
}

func application(application: UIApplication, 
didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    do {
        try Marigold().startEngine(SDK_KEY)
    } catch {
        // Handle error
    }
    return true
}

SwiftUI Integration

When creating a SwiftUI project from scratch Xcode doesn't create an AppDelegate class automatically as it does for older projects. The following are details on how to set up an AppDelegate in SwiftUI and call startEngine from it.

First create a custom class that inherits from NSObject and conforms to the UIApplicationDelegate protocol, like this:

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        do {
            try Marigold().startEngine(SDK_KEY)
        } catch {
            // Handle error
        }
        return true
    }
}

In the example above didFinishingLaunchingWithOptions was added which is needed to call startEngine but you can also implement any other methods you need here as well.

Now in your App scene, use the UIApplicationDelegateAdaptor property wrapper to tell SwiftUI it should use your AppDelegate class for the application delegate.

@main
struct SwiftUI_TestApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Swift UI is responsible for creating that delegate and looking after its lifetime, so you can go ahead and add any other app delegate functionality to that class to have it called.

🚧

It is important that startEngine method is called at the earliest possible opportunity, calling it later in the app lifecycle can have unintended consequences.

Push Authorization Options

By default, calling startEngine: will request push authorization to display Alerts, Badges and Sounds to the user. This will display a popup to the user requesting their permission to display these notification options. We recommend that you delay this popup and provide an introductory flow to display the value of your app's push notifications before prompting the user for permission. If you want to do that you can use another method that allows you to specify which push authorizations you would like to request.

#import <Marigold/Marigold.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	[[Marigold new] startEngine:SDK_KEY withAuthorizationOption:STMPushAuthorizationOptionProvisional]; // Obtain SDK key from your Sailthru Mobile app settings
  return YES;
}

func application(application: UIApplication, 
didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
	Marigold().startEngine(SDK_KEY, with: .provisional) // Obtain SDK key from your Sailthru Mobile app settings
  return true
}

The available authorization options are detailed below.

Test your integration

To make sure it's working, launch your app in your simulator or on your iOS device. You if you retrieve the Device ID from the SDK you should be able to confirm it has been created on the platform.

Next Steps

1. Setup Push Notifications for iOS to ensure your users can receive push notifications when the app is closed.
2. Setup in-app messages to enable Marigold's rich In-App Messages
3. Collect user data to help in segmenting and targeting your users based on their activity.