Basic Automated Setup

Goal

This guide explains how to perform a basic automatic integration of the Mapp Engage iOS SDK into your project. You'll only need to add one method and configure your plist file.

For more advanced manual integrations:

• Manual Integration in Swift

• Manual Integration in Objective-C

Procedure

Step 1: Download the SDK

Download the iOS SDK. If using SPM for integration, skip directly to the SPM section.

Step 2: Add the Import Statement

#import <AppoxeeSDK/AppoxeeSDK.h>

#import <AppoxeeSDK/AppoxeeSDK.h>

Step 3: Configure application:didFinishLaunchingWithOptions

After importing the SDK, update the application:didFinishLaunchingWithOptions: method in AppDelegate:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Appoxee.shared()?.engageAndAutoIntegrateWithLaunchOptions(launchOptions, andDelegate: nil, with: .L3)
    return true
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[Appoxee shared] engageAndAutoIntegrateWithLaunchOptions:launchOptions andDelegate:nil with:L3];
    return YES;
}

Ensure the AppoxeeConfig.plist file is present in the project as this method relies on its configuration.

[Appoxee Error] Network protocol error with HTTP code: 403

Appoxee.shared()?.engageAndAutoIntegrate(launchOptions: launchOptions, andDelegate: nil, notificationDialog: false, with: .L3)

[[Appoxee shared] engageAndAutoIntegrateWithLaunchOptions:launchOptions andDelegate:nil notificationDialog:NO with:L3];

Step 4: Create the AppoxeeConfig.plist File

Create a file named AppoxeeConfig.plist in your project and include the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>inapp</key>
    <dict>
        <key>custom_fields</key>
        <array>
            <string>customString</string>
            <string>customNumber</string>
            <string>customDate</string>
        </array>
        <key>media_timeout</key>
        <integer>5</integer>
    </dict>
    <key>sdk</key>
    <dict>
        <key>app_id</key>
        <string><your-app-id></string>
        <key>dmc_system_id</key>
        <integer><your-dmc-system-id></integer>
        <key>sdk_key</key>
        <string><your-sdk-key></string>
        <key>jamie_url</key>
        <string><jamie-url-from-account-manager></string>
        <key>is_eu</key>
        <true/>
        <key>open_landing_page_inside_app</key>
        <false/>
    </dict>
</dict>
</plist>

Plist Keys Reference:

Using Swift Package Manager (Optional)

1. Go to our GitHub, and copy the git URL as you would for git clone.

2. Paste it inside the package search window and set up your version number. Then press Add Package.

3. After adding the package, go to Targets and select the target with the same name as your project.

4. Next, go to the Build Phases tab and expand the Copy Bundle Resources section.

5. After, expand the Package folder on the left side, then expand the SDK folder and drag and drop the AppoxeeInappResources file. Unselect Copy If Needed, select Create folder references, and press OK.
   

6. After that, you will be able to build a project. The same procedure applies to the Push notification Package. However, the git URL is different, and the name of the branch corresponds to the task.

7. If you want to update the package, right-click on it and select the update package option.

Required System Frameworks for SPM Integration

When integrating the SDK via Swift Package Manager, you must manually link the required system frameworks.

1. Go to Targets and select your app target.

2. Open the Build Phases tab.

3. Expand Link Binary With Libraries.

4. Add the following frameworks:    

   • WebKit.framework

   • UserNotifications.framework

The SDK uses WebKit components, for example WKWebView. If WebKit.framework is not linked, the build may fail with undefined symbol errors such as WKWebView, WKPreferences, or WKWebViewConfiguration.

Using Cocoapods (Optional)

1. Add the following to your Podfile:

target 'YourApp' do
    pod 'MappSDK'
end

2. Run:

pod update

Additional Features

Push Permission Dialog

The push notification permission dialog appears by default on the first app launch. To change when it appears, see Push Notifications.

Foreground Notifications

From iOS 10 onward, you can decide whether to display notifications while the app is in the foreground. By default, the SDK does not show them. To show them, set Appoxee.shared()?.showNotificationsOnForeground = true. Learn more in the foreground notification guide.

Acting as the UNUserNotificationCenter Delegate

With the automatic integration, the SDK handles the notification callbacks for you. If your app sets itself as the UNUserNotificationCenterDelegate, for example to handle notification taps itself, it takes over these callbacks. Your app must then implement both delegate methods:

• userNotificationCenter(_:willPresent:withCompletionHandler:): decides how a notification is shown while the app is in the foreground. Setting showNotificationsOnForeground alone has no effect in this case. See Foreground Notifications.

• userNotificationCenter(_:didReceive:withCompletionHandler:): called when the user taps a notification. Forward every tap to the SDK. For code examples, see Forward Notification Taps in Manual Integration in Swift or Manual Integration in Objective-C.

Warning

If your app does not forward notification taps, the landing page or deep link may not open and the app opens on its home screen instead. Custom notification actions may not be processed, and push clicks are not tracked.

Note

Class and method names in the SDK use Appoxee, the legacy name of the Mapp Engage SDK.

Troubleshooting

• Error 403: Ensure the is_eu flag matches your data center.

• Landing Pages Not Opening Inside App: Check the open_landing_page_inside_app configuration. This setting only controls whether the landing page opens inside the app or in the browser. It does not replace tap forwarding.

• App Opens on Its Home Screen Instead of the Landing Page: If your app is the UNUserNotificationCenterDelegate, check that it forwards notification taps to the SDK. See Acting as the UNUserNotificationCenter Delegate. If you use several push providers, also check that your filter does not discard Mapp notifications. Without forwarding, push clicks are not tracked either.

• SDK Version Requirement: Features like delayed notification dialogs require SDK version 6.0.0 or above.