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

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

2. Add the Import Statement

   • Objective-C
     In your AppDelegate.m file, add this line:

     #import <AppoxeeSDK/AppoxeeSDK.h>

   • Swift
     Add the following to your Objective-C bridging header:

     #import <AppoxeeSDK/AppoxeeSDK.h>

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

   • Objective-C:

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

   • Swift:

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

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

     Configuration Details

     SDK Key and Data Center

     • Enter the SDK Key (provided during app configuration).

     • Set the is_eu flag based on your data center location:

       • YES for the EU

       • NO for the US

     ⚠️ Important: Mismatching the flag with your data center environment will result in the following error in Xcode:

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

     Server Enums

     The with parameter in the integration method accepts enums for server selection:

     • L3, EMC, EMC_US, or CROC are valid options provided by the account manager.

     • TEST, TEST55, and TEST61 are for development purposes only and should not be used in production.

     Push Notification Permissions

     • By default, users are prompted for notification permissions at the first app launch.

     • To delay this and trigger the dialog later, use the notificationDialog parameter:

     Objective-C:

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

     Swift:

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

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:

   Key	Type	Description
   app_id	String	Numeric Mapp Engage application identifier provided by your account manager.
   dmc_system_id	Integer	System identifier for your Mapp Engage instance.
   sdk_key	String	Per-app SDK key generated when the iOS channel is created in Mapp Engage.
   jamie_url	String	Hostname of the In-App message backend assigned to your tenant.
   is_eu	Boolean	true for EU data center, false for US.
   open_landing_page_inside_app	Boolean	If true, push landing pages open in an in-app web view; otherwise the system browser opens.
   inapp.custom_fields	Array of String	Names of custom attributes to expose as targeting variables for In-App messages.
   inapp.media_timeout	Integer	Seconds the SDK waits for In-App media to load before falling back to a text-only message.

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

1. Push Permission Dialog: The push notification permission dialog appears by default on the first app launch. Refer to the documentation to customize its display logic.

2. Handle Foreground Notifications: From iOS 10 onward, you can decide whether to display notifications while the app is in the foreground. Learn more in the foreground notification guide.

3. Becoming a UNUserNotificationCenterDelegate: IF you choose to act as the UNUserNotificationCenterDelegate, you must forward its methods to Appoxee.

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.

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