Skip to end of metadata
Go to start of metadata

 

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

2.1 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.

2.1.1 Install and initiate the SDK

Using React Native? See this Documentation for instructions on using the Accengage SDK as iOS Native Module.

Installation

     

    The fastest and easiest way to add the SDK in your project is using CocoaPods.

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

    2. If you don't already have a Podfile in your XCode project directory, create one with the following command

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

    4. Install the SDK

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


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

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

    2.  Add the Accengage SDK to your Cartfile:

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

    3. Execute the following command in your Cartfile directory:

     

    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.

    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.

    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.

    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:

       

      Initialization

      Now you're ready to begin implementing. Start the library in your AppDelegate application:didFinishLaunchingWithOptions: method. Make sure to start the library on the main thread. Otherwise, it will throw an exception.

      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.

        You can also programmatically override the configuration values:

          Starting the SDK with ACCOptInEnabled as the optIn 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 (or resume). Note that you'll need to call setGeofenceServiceEnabled and setBeaconServiceEnabled 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.

            Note that you'll need to call setDataOptInEnabled method at every SDK launch (after the startWithOptIn/startWithConfig:OptIn method)

            While the SDK is disabled, calling its methods will not have an effect and the return values will be false, nil or 0. Several method nullability annotations have been changed to reflect this so please make sure that your application is capable of handling these different values.

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

              To retrieve the current opt-in status, use the following methods:

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

                  or:

                    2.1.2 Registering

                    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.

                    Important

                    Your must register for user notifications every time your app is launched.

                      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.


                        Note

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

                         

                        2.1.3 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. 

                          Grouped notifications :

                          With iOS 12, notifications are no longer displayed in chronological order, but can be grouped by app or by app+topics. 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”.

                           

                          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.

                          2.2 RECOMMENDED CONFIGURATIONS

                          2.2.1 Handling Notification 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.

                            2.2.2 Media attachments

                            1. iOS 10 introduced support for rich 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 :

                              Rich notifications are available on iPhone 5s or later, iPad Pro, iPad Air or later, and iPad mini 2 or later.

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

                               

                              Deployment target

                              By default, XCode set the most recent iOS version available as deployment target. If you run your application on a device that has an older iOS version, push notifications with media attachment won't be able to work. We recommend to set 10.0 as deployment target.

                                 

                                1. In your Podfile, add the pod Accengage-iOS-SDK-Extension to your newly created target

                                2. Then, update your Cocoapods project.

                                 

                                • 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. 

                                • 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.
                                • 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. 

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

                                • Verify  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 :

                                   

                                   



                                2.2.3 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 the value at a given number, or reset 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 : 

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

                                  Or by using the method provided by our SDK: 

                                   


                                    By default, the SDK will reset the badge any time a user starts the app or resumes it from the background or opens a push notification. This autoreset option can be disabled. 

                                      3.UPDATING THE SDK VERSION (MIGRATION GUIDE)

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

                                      4.SEND A BASIC PUSH

                                      Get device ID or Token

                                      The Accengage SDK creates a unique Device ID 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.

                                      To do so, please use this method :

                                        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.

                                        • No labels