SDK Integration

In this section, we will help you integrate the SDK smoothly trough different steps:

  • Get you started easily by looking at the Sample Applications
  • Integrate the SDK in a basic way
  • Register to Push Notifications
  • Activate logging in order to help you debug the integration
  • Go further with some recommended integration
  • Test your configuration

We will also look specifically at the case of SDK version update in case you already have integrated the Accengage SDK

Basic and mandatory steps

Sample Application

To see examples of the basic integration as well as the advanced features, take a look at our sample code.

Install the SDK

CocoaPods

  1. First of all, please ensure that you have the CocoaPods dependency manager installed by executing the following command:

    $ sudo gem install cocoapods
  2. If you don't already have a Podfile in your Xcode project directory, create one with the following command:

    $ pod init
  3. Add the following lines to your Podfile and make sure to add use_frameworks! to your Podfile target:

    # Accengage specs source repo
    source 'https://github.com/urbanairship/ios-pod-specs.git'
    
    # CocoaPods master specs repo
    source 'https://github.com/CocoaPods/Specs.git'
    
    use_frameworks!
    
    target 'YOUR_APP_TARGET' do
       pod 'Accengage-iOS-SDK', '~> 7.1'
    end
  4. Install the SDK

    $ pod install

.xcworkspace file will be created for your application. Use this file for all future developments on your application.

Carthage

Before you start, please make sure that you have Carthage installed.

  1. You can install it using Homebrew by executing the following commands:

    $ brew update
    $ brew install carthage
  2. Add the Accengage SDK to your Cartfile:

    github  "Accengage/accengage-ios-sdk-releases"
    github  "Accengage/accengage-ios-extension-sdk-releases"

    or if you prefer to target a specific version e.g.

    github  "Accengage/accengage-ios-sdk-releases" == 6.4.1
    github  "Accengage/accengage-ios-extension-sdk-releases" == 2.0.0
  3. Execute the following command in your Cartfile directory:

    $ carthage update

Manual Installation

This steps explains how to manually install the SDK.

  1. First, download and unzip the latest version of the iOS SDK.
  2. Drag .framework into the top level of your Xcode project. When prompted, use the checkboxes to add the framework to the specific target for which you are compiling. Make sure you check the Copy items if needed box.

    Img

  3. In your application target you need to add a Copy Files build phase to your target. From the Build Phases panel of your target's configuration:

    1. Press the + button from the top left region
    2. Select New Copy Files Phase. A new entry will appear in the Build Phases list.
    3. Change the destination selector to Frameworks
    4. Find the Accengage.framework and drag it into this new section.

    Img

  4. Add a new Run Script Phase and paste the content of the this script in the newly added section. This script works around an App Store submission bug triggered by universal frameworks.

    Img

  5. Verify Enable Modules and Link Frameworks Automatically are enabled in the target Build Settings.

To take advantage of the iOS 10 media attachments, you need to create a Notification Service Extension in your application. This process is explained in the Media attachments section of the documentation.

Configuration file

First, get an empty configuration file to add to your project from this link.

Drag the AccengageConfig.plist file you just downloaded into the root of your Xcode project and add it to all targets then complete it with your own partner id and private key.

Import

Import Accengage at the top of your AppDelegate and any class that uses it:

Objective-C:

#import <Accengage/Accengage.h>

Swift:

import Accengage

Start the SDK

Now you're ready to begin implementing. Start the library in your AppDelegate application:didFinishLaunchingWithOptions: method.

To ensure GDPR compliance, you'll need to start the SDK and pass the Opt-In management type as a parameter. This means either that your application manages the user Opt-In or if that you wish to explicitly indicate that it's not the case.

If you pass ACCOptInEnabled as a value, Accengage SDK will wait until setDataOptInEnabled method is called. If you pass ACCOptInDisabled, Accengage will start with all services enabled.

Objective-C:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Start the SDK with the configuration set in the AccengageConfig.plist file
    [Accengage startWithOptIn: ACCOptInEnabled];

    return YES;
}

Swift:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    // Start the SDK with the configuration set in the AccengageConfig.plist file
    Accengage.startWithOpt(ACCOptIn.enabled)

    return true
}

You can also programmatically override the configuration values:

Objective-C:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    ACCConfiguration *config = [ACCConfiguration defaultConfig];
    // config.IDFACollectionEnabled = NO;

    [Accengage startWithConfig:config optIn:ACCOptInEnabled];

    return YES;
}

Swift:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    let config = ACCConfiguration.defaultConfig()
    // config.isIDFACollectionEnabled = false

    Accengage.start(withConfig: config optIn:ACCOptIn.enabled)

    return true
}

Starting the SDK with ACCOptInEnabled as the Opt-In management type means that the SDK will be disabled until setDataOptInEnabled: method is called. Typically, you would call this method to inform the SDK of the user's decision regarding the data Opt-In. Passing YES means that Accengage SDK will start. Note that you'll need to call setGeofenceServiceEnabled: and setBeaconServiceEnabled: methods to enable these services. Also, you'll need to call registerForUserNotificationWithOptions after this method to enable push notifications. Passing NO means that all Accengage services will be stopped.

Objective-C:

[Accengage setDataOptInEnabled:YES];

Swift:

Accengage.setDataOptInEnabled(true)

Accengage SDK provides a separate method to enable/disable the geolocation data Opt-In: setGeolocOptInEnabled:.

Objective-C:

[Accengage setGeolocOptInEnabled:YES];

Swift:

Accengage.setGeolocOptInEnabled(true)

To retrieve the current Opt-In status, use the following methods:

Objective-C:

BOOL dataOptIn = [Accengage isDataOptInEnabled];
BOOL geolocOptIn = [Accengage isGeolocOptInEnabled];

Swift:

let dataOptIn = Accengage.isDataOptInEnabled()
let geolocOptIn = Accengage.isGeolocOptInEnabled()

However, if you decide not to manage GDPR Opt-In within the Accengage SDK, you can still use the following methods:

Objective-C:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Start the SDK with the conf set in the AccengageConfig.plist file
    [Accengage start];

    // You can also programmatically override the configuration values
    // ACCConfiguration *config = [ACCConfiguration defaultConfig];
    // config.IDFACollectionEnabled = NO;
    // [Accengage startWithConfig:config];

    return YES;


    return YES;
}

Swift:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    // Start the SDK with the conf set in the AccengageConfig.plist file
    Accengage.start()

    // You can also programmatically override the configuration values
    // let config = ACCConfiguration.defaultConfig()
    // config.isIDFACollectionEnabled = false
    // Accengage.start(withConfig: config)

    return true
}

Register to Push Notifications

In order to register for user notifications, you can call the registerForUserNotificationsWithOptions: method. This means that you're no longer required to maintain the registration code by yourself, just call this method and the library will request notification authorization for you.

Objective-C:

// Register for notification
ACCNotificationOptions options = (ACCNotificationOptionSound | ACCNotificationOptionBadge | ACCNotificationOptionAlert | ACCNotificationOptionCarPlay | ACCNotificationOptionProvisional | ACCAuthorizationOptionProvidesAppNotificationSettings);

[[Accengage push] registerForUserNotificationsWithOptions:options];

Swift:

// Register for notification
Accengage.push()?.registerForUserNotifications(options: [.notificationOptionSound, .notificationOptionAlert, .notificationOptionBadge, .notificationOptionCarPlay, .notificationOptionProvisional, .authorizationOptionProvidesAppNotificationSettings])

Calling the method above will request authorization for notifications with the given options and set of default notification categories provided by Accengage. If you want to add more categories for interactive notifications, you should call the setCustomCategories: first.

Objective-C:

// The app custom categories set
[[Accengage push] setCustomCategories:customCategories];

// Register for notification
ACCNotificationOptions options = (ACCNotificationOptionSound | ACCNotificationOptionBadge | ACCNotificationOptionAlert |ACCNotificationOptionCarPlay| ACCNotificationOptionProvisional | ACCAuthorizationOptionProvidesAppNotificationSettings);

[[Accengage push] registerForUserNotificationsWithOptions:options];

Swift:

// The app custom categories set
Accengage.push().customCategories = customCategories

// Register for notification
Accengage.push()?.registerForUserNotifications(options: [.notificationOptionSound, .notificationOptionAlert, .notificationOptionBadge, .notificationOptionCarPlay, .notificationOptionProvisional, .authorizationOptionProvidesAppNotificationSettings])

Custom categories must be declared in the Accengage Back Office. See our guide for more details.

Manage iOS 12 features

Provisional authorization

With iOS 12, developers have the ability to start sending notifications without explicit permission, i.e, on a trial basis. Apple calls this new notification management protocol provisional authorization.

Provisional authorization comes with quiet notifications. You can ask for permission to send to notification centre - and potentially get rejected - or automatically send them quietly on a trial basis.

Custom settings authorization

In order to register for user notifications with provisional authorization and activates notification settings, you should call the registerForUserNotificationsWithOptions: method with the new authorization options provided by iOS 12.

  • ACCNotificationOptionProvisional: to activates the provisional authorization.
  • ACCAuthorizationOptionProvidesAppNotificationSettings: to indicates that the system should display a button for notification settings.

Objective-C:

// Register for notification
ACCNotificationOptions options = (ACCNotificationOptionSound | ACCNotificationOptionBadge | ACCNotificationOptionAlert | ACCNotificationOptionCarPlay | ACCNotificationOptionProvisional | ACCAuthorizationOptionProvidesAppNotificationSettings);

[[Accengage push] registerForUserNotificationsWithOptions:options];

Swift:

// Register for notification
Accengage.push()?.registerForUserNotifications(options: [.notificationOptionSound, .notificationOptionAlert, .notificationOptionBadge, .notificationOptionCarPlay, .notificationOptionProvisional, .authorizationOptionProvidesAppNotificationSettings])

Grouped notifications

With iOS 12, notifications are no longer displayed in chronological order, but can be grouped by app or by app+topic. The app displays the grouped notification on the notification center.

To group notification by topic, you should affect a thread identifier to your notification. For that, you must add a custom parameter when creating the Push Notification on the Accengage dashboard using the key “a4sThreadId”.

Img

  1. Summary text:

    Once the notifications are grouped, iOS developer can add a summary description that can be customized. The format of the summary text is "X more notifications from XX". (X = number of notification grouped | XX = part that can be customized)

  2. Custom grouping:

If you want to customize the summary text, then add the summary argument and the summary argument count by adding the two keys “a4sSummaryArg” and “a4sSummaryArgCount” as custom parameters.

  • a4sSummaryArgCount: Add the new custom parameter with the key a4sSummaryArg to add the number of items the notification adds to the category’s summary format string.
  • a4sSummaryArg: Add the new custom parameter with the key a4sSummaryArgCount to add the string the notification adds to the category’s summary format string.

Send a basic push

Get the Device ID

The Accengage SDK creates a unique Device ID (or IDFV) at first launch. Fetching this ID can be interesting if you would like to store it in your system, in order to trigger API call for instance, or for any other reason.

You can get your device ID as NSString, by accessing the accengageId property:

Objective-C:

[Accengage shared].accengageId

Swift:

Accengage.shared()?.accengageId

Send a push

In order to verify that your integration is correctly done, we recommend you to send a push to yourself.

To do so, please follow the steps explained in our User Guide.

Activate logging

Two steps are required to enable logging. First, you have to allow your application to communicate with our log application. Then you have to programmatically enable console logs. These steps are described right below:

Configure logging application

Accengage provides a log application (called ACCInfos). In a first hand, it will help you to identify your own device for testing.

In the second hand, it will provide contextual logs to the Accengage support team during SDK integration, when there is an unexpected behaviour.

In order to make your application capable of communicate with our log application, you will need to follow the following steps:

  1. Add the url scheme bma4sreceiver to the scheme whitelist in your application Info.plist file (See the section "Configure URL Schemes" for more informations.

    <key>LSApplicationQueriesSchemes</key>
    <array>
      <string>bma4sreceiver</string>
    </array>
  2. Add a localhost exception to the NSAppTransportSecurity key in your Info.plist file.

    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSExceptionDomains</key>
        <dict>
            <key>localhost</key>
            <dict>
                <key>NSExceptionAllowsInsecureHTTPLoads</key>
                <true/>
            </dict>
        </dict>
    </dict>

Img

Enabling console logs

Once your application is able to communicate with our log application, you can enable Accengage SDK logs with the setLoggingEnabled: method:

Objective-C:

[Accengage setLoggingEnabled:YES]

Swift:

Accengage.setLoggingEnabled(true)

Handling notifications custom parameters

Custom parameters are parameters which are sent together with the push notifications, but which are invisible to the recipients, and which have many interests.

For instance, thanks to custom parameters, you can manage deep links, trigger certain features within your app, or transmit certain information (such as a source) to an analytics SDK.

To enable that, you can set up the custom parameters in the Accengage dashboard when composing a Push message, and your application needs to handle them and trigger the wanted behaviours.

To retrieve the custom parameters with a remote notification and its actions, you'll need to set an Accengage Push delegate object. Your object must adopt the ACCPushDelegate protocol.

Objective-C:

[Accengage push].delegate = self;

Swift:

Accengage.push().delegate = self

Media attachments

  1. iOS 10 introduced support for rich Push Notifications, which added the ability to send Push Notifications with media attachments such as images, animated gifs, sounds and videos.

    It is a very interesting way to enhance the User Experience and the performance of your Push Notifications.

    Here it is an example of Push Notification with a media attachment:

    Img

    To enable this functionality, you will need to create a Notification Service Extension.

    Img

CocoaPods Installation

  1. Once your notification service is created, add the pod Accengage-iOS-SDK-Extension to your newly created target in your Podfile:

    # Add it to your Podfile
    target 'YOUR_NOTIFICATION_SERVICE_EXTENSION_TARGET' do
     pod 'Accengage-iOS-SDK-Extension', '~> 2.0.0'
    end
  2. Then, update your Cocoapods project:

    $ pod update
  3. Finally, inherit from ACCNotificationServiceExtensionin NotificationService and replace all the code generated by Xcode by the following one:

Objective-C:

//  NotificationService.h
#import <AccengageExtension/AccengageExtension.h>

@interface NotificationService : ACCNotificationServiceExtension
@end
//  NotificationService.m
#import "NotificationService.h"

@implementation NotificationService
@end

Swift:

import AccengageExtension

class NotificationService: ACCNotificationServiceExtension {
}

Manual Installation

  • Once your notification service is created, download and unzip the latest version of the iOS SDK Extension.
  • Drag AccengageExtension.framework into the top level of your Xcode project. When prompted, use the checkboxes to add the framework to the notification service target. Make sure you check the Copy items if needed box.

    Img

  • In your application target you need to add a Copy Files build phase to your target. From the Build Phases panel of your target's configuration:

    1. Press the + button from the top left region.
    2. Select New Copy Files Phase. A new entry will appear in the Build Phases list.
    3. Change the destination selector to Frameworks.
    4. Find the AccengageExtension.framework and drag it into this new section.

    Img

  • Add a new Run Script Phase and paste the content of the this script in the newly added section. This script works around an App Store submission bug triggered by universal frameworks.

    Img

    The order of the build phases is important. The Run Script phase must be added after (or placed below) the Copy Files phase.

  • Verify that Enable Modules and Link Frameworks Automatically are enabled in the target Build Settings.

Finally, inherit from ACCNotificationServiceExtensionin NotificationService and replace all the code generated by Xcode by the following one:

Objective-C:

//  NotificationService.h
#import <AccengageExtension/AccengageExtension.h>

@interface NotificationService : ACCNotificationServiceExtension
@end
//  NotificationService.m
#import "NotificationService.h"

@implementation NotificationService
@end

Swift:

import AccengageExtension

class NotificationService: ACCNotificationServiceExtension {
}

Badges

Accengage lets you manage the value of your application badge when sending a Push Notification. Within the Accengage dashboard, you can decide to increment it, set a specific value, reset it to 0 or remove it.

By default, the Accengage SDK will reset the badge any time a user launches the app, resumes it from the background, or opens a push notification.

This autoreset option can be disabled by following this instruction:

Objective-C:

[Accengage push].badgeAutoResetEnabled = NO;

Swift:

Accengage.push().isBadgeAutoResetEnabled = false

You can reset the badge number within your application by setting applicationIconBadgeNumber:

Objective-C:

[UIApplication sharedApplication].applicationIconBadgeNumber = 0;

Swift:

UIApplication.shared.applicationIconBadgeNumber = 0;

Or by using the method provided by our SDK:

Objective-C:

[[Accengage push] resetBadge];

Swift:

Accengage.push().resetBadge()

Update the SDK version

Migration guide

Your migrating from an older version ? Check out our Migration Guide to get started using the latest version.