Skip to end of metadata
Go to start of metadata

 

 

Important

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

Introduction

Accengage technology allows the sending of push notifications on mobile applications, Websites and Facebook Messenger.

Available in SAAS mode, its offer a large panel of functionalities in order to help advertisers to accelerate their mobile users engagement :

  • Notifications with Buttons, Images, Videos, GIFs, Sounds ...
  • In-Apps messages
  • Inbox Messages
  • Real time segmentation
  • Dynamic customization (templates, messages) 
  • Geomarketing via Geofencing and Beacons,
  • Advanced automation with real-time triggers,
  • Connectors with leading CRM & DMP solutions on the market
  • APIs for sending and retrieving data etc.. 

You will discover them gradually, by reading this documentation. If needed, do not hesitate to contact our friendly support team (http://ticket.accengage.com)

Section 1 - Getting started

 

In this section, we will help you get started by going through the preliminary steps for a smooth integration:


- Configure Push Notifications in your app and generate a certificate on the Apple developer portal
- Set the Accengage dashboard correctly
- Create URL Schemes for deep linking


During these steps, you will need to use Xcode, your Apple Developer account, as well as the Accengage Dashboard.

1.1 Requirements and important information on the iOS SDK

The Accengage iOS SDK is provided as a dynamic framework and is compatible with:

- Xcode 9
- iOS 8 and higher.

In terms of size, the SDK will increase your app download size by ~608 Kb.

In order to integrate it, you will need:

- A partner id and a private key for each application and each environment (Development and
production), available for registered customers on our platform. If you do not have a partner
id and private key yet, please contact our support (http://ticket.accengage.com).

See below to set these correctly with your other credentials : 

- To generate a Push Notification certificate (see below)

- The Bundle Id of your application which should be entered in the application form in the Accengage dashboard (Settings > Manage application > Edit).

1.2 Activate Push Notifications

Enable Push Notifications in Xcode

  1. In the project editor, choose a target and click Capabilities.
  2. In the Push Notifications section, click the switch to turn it from OFF to ON.

 

Generate and export an APNS client TLS certificate from the Apple developer portal

Generate an APNS client TLS certificate

You need to generate a separate client TLS certificate for each app you distribute that uses push notifications including Development and Production versions.

It is important that you generate a Development (Sandbox) Push Notification certificate to use with a Development Provisioning Profile, and/or a Production Push Notification certificate to use with an Ad Hoc or Distribution Provisioning Profile. They will be used in 2 separate applications within Accengage Dashboard (see below) and it will be important that you respect this differentiation.

Generating the certificate fully enables push notifications for the associated App ID. In your developer account, you will notice that the Push Notifications service for the App ID changes automatically from Configurable to Enabled.

  1. In your developer account, go to Certificates, Identifiers & Profiles and if necessary, choose the operating system from the pop-up menu on the left (for macOS apps, choose OS X).
  2. Under Certificates, select All.
  3. Click the Add button + in the upper-right corner.

  4. Under Production, select the “Apple Push Notification service SSL (Sandbox & Production)” checkbox, then click Continue.

  5. Choose an App ID from the App ID pop-up menu, and click Continue.
  6. Choose the explicit App ID that matches your bundle ID.
  7. Follow the instructions to create a certificate signing request on your Mac, and click Continue.
  8. Click Choose File.
  9. In the dialog that appears, select the certificate request file (a file with a .certSigningRequest file extension), and click Choose.
  10. Click Continue.
  11. Click Download and double-click the downloaded file (a file with a .cer file extension) to add the certificate to your keychain.
  12. Click Done.

Create a certificate signing request

  1. Launch Keychain Access located in /Applications/Utilities.

  2. Choose Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority.
  3. In the Certificate Assistant dialog, enter an email address in the User Email Address field.
  4. In the Common Name field, enter a name for the key (for example, Gita Kumar Dev Key).
  5. Leave the CA Email Address field empty.
  6. Choose “Saved to disk”, and click Continue.

 

Export the client TLS identity from your Mac

Export the identity from the keychain on the Mac where you created it, and copy it to the appropriate place on the server that runs the provider code and connects with the development or production version of APNs.

  1. Launch Keychain Access.
  2. In the Category section, select My Certificates.
  3. Find the certificate you want to export and disclose its contents.

  4. You’ll see both a certificate and a private key.
  5. Select both the certificate and the key, and choose File > Export Items.
  6. From the File Format pop-up menu, choose a file format that your server accepts.
  7. Enter a filename in the Save As field, and click Save.
  8. The certificate and key are saved to the location you specified as a text file in the Personal Information Exchange format (a file with a .p12 file extension).

1.3 Configure the Accengage dashboard for Push Notifications

 


Once you have exported your Push Notification certificate, you need to upload it in the Accengage Dashboard. Please go to Settings > Manage Application and click on the pencil to edit the configurations. You should have 2 separate applications, 1 for the Development environment, and 1 for Production. In the relevant application, you should:

- upload the push notification certificate

- enter its password

- tick the right type of push notification certificate

- enter the right Bundle Id

It is very important that you respect the following configuration:
- Use your Development Partner Id and private key, with a Development Provisioning profile within your application, a Development Push Notification Certificate, as well as set the Push Notification certificate as “Development” in the Accengage Dashboard (Settings > Manage application > Edit > Development certificate)
- Use your Production Partner Id and private key, with a Distribution or Ad Hoc Provisioning profile within your application, a Production Push Notification Certificate, as well as set the Push
Notification certificate as “Production” in the Accengage Dashboard (Settings > Manage application > Edit > Development certificate)
- Also make sure that you enter the right Bundle Id for the right application within the Accengage dashboard.
If you do not respect this consistency, then you will end up with Development tokens within your Production environment or the opposite and this will create disconnections when you try and send Push Notifications, which means you might not receive some Push Notifications!
This is a common mistake which causes time consuming investigations. Please make sure that you have followed the previous instruction with attention to avoid those mistakes.

Once you have set this information up, you are now ready to integrate the SDK!

1.4 Configure URL Schemes

Creating URL schemes

Deep Linking is becoming very important, it's a great way to enhance the effectiveness of your app's marketing campaigns. It will allow you to open a specific view of your app from another app, from a push message, from an in-app message or even from a website to your app.

To take advantage of it, you must create a custom URL Scheme associated with your application. A URL scheme lets you communicate with other apps through a protocol that you define. To find out more, check out Apple documentation.

To register your URL Scheme:

  1. Select your app target from the sidebar, then select the Info tab.
  2. Open the URL Types expander and click +.
  3. In the URL Schemes field, enter your_app_url_scheme.
  4. Assign a unique identifier to the scheme to ensure uniqueness and avoid name collisions, so we’ll use com.myapp.url for the example.

 

 

That’s it! To verify that everything works:

  1. Run your app
  2. Open Safari on the same device
  3. Type your_app_url_scheme:// in the address bar, then press Go
  4. You should arrive on the expected page

Whitelisting URL Schemes

iOS 9 introduces changes that impact URL scheme management. For more details, you can consult Apple's documentation.

Make sure that your application Info.plist includes the LSApplicationQueriesSchemes set with your app's URL Scheme (see previous section to find out how to create your app's URL scheme) and every scheme your app will query.

Section 2 - 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

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.

                                        Section 3 - Advanced push configuration

                                         

                                        Have a splashcreen in your app ?

                                        Allowing a content to be displayed in your splashcreen can affect the push behaviour.

                                        For this reason, a method exists to prevent the display of any Accengage content once the splashcreen is loading. Please check this page for more information.


                                        3.1 Customize the SDK default launching configuration

                                        The library provides a number of advanced configuration features that can be controlled with the ACCConfiguration object.

                                        The configurations can be set simply by using the AccengageConfig.plist you've added to your project, or at runtime using the exposed properties of the ACCConfiguration object. See the ACCConfiguration documentation for the full list of configuration options.

                                         

                                        IDFA collection

                                        The IDFA (Identifier for Advertisers), is automatically collected by the library. Note that you can disable the IDFA collection by setting the property to NO.

                                        Automatic integration

                                        It's not required to implement the notification-related delegate methods. The library can intercept the UIApplicationDelegate and the UNUserNotificationCenterDelegate messages and forward them to your original delegate.

                                        This should be compatible with the majority of application use cases, but if you prefer, you can disable this behavior.

                                        If you choose to disable the automatic integration, you will need to implement all notification-related UIApplicationDelegate and UNUserNotificationCenterDelegate methods. See the Push documentation for more details.

                                        Tracking mode

                                        Depending on your privacy rules, you can decide to choose the restricted tracking mode which disables the collection of certain device data such as connection type, carrier name, local date and jailbreak state.

                                        Note that if you use the restricted mode, some advanced targeting features may not be available. This restriction is not recommended for most integrations.

                                        Session timeout

                                        The library provides automated session management. This value indicates how long (in seconds) the app may be in the background before starting a new session upon resume. A default implementation has a session timeout period of 5 minutes. If the app remains in the background for longer than the session timeout period, the next time it's opened a new session will be started.

                                         

                                        Note

                                        Each new session equals to a new application visit which means that new server calls are made.

                                        It is for this reason that we recommend that you keep the session timeout period set to 5 minutes.

                                        Delay SDK Launch

                                        If you prefer to start the SDK with a delay (e.g. as a result of a user action), you'll need to pass the launch options information to the SDK. This information is provided by the system in the didFinishLaunchingWithOptions callback and should be set using the launchOptions property of the ACCConfiguration object. 

                                        Custom notification sounds

                                        You can specify a custom sound, that iOS will play when it receives a local or remote notification for your app. For more details, you can consult Apple's documentation.

                                        Remember that the default sound is played when:

                                        • The sound file is not found.
                                        • The sound is longer than 30 seconds.
                                        • The data format is invalid. Accepted data formats are: aiff, wav, or caf.

                                        To add the sound file to your project, you can simply drag and drop it to your resource folder. Make sure you check the box Copy items if needed.

                                        In the Accengage dashboard, you can easily specify this sound when composing a push message by selecting "custom" in the sound section, and enter the file name with its extension (customsound.wav for instance).

                                        Prefer a short file name.

                                        Configure interactive notifications

                                        Interactive notifications give the user a quick and easy way to perform relevant tasks in response to a notification. Instead of the user being forced to launch your app, the interface for an actionable notification displays custom action buttons that the user can tap. When tapped, each button dismisses the notification interface and forwards the selected action to your app for immediate handling. Forwarding the action to your app avoids the need for the user to navigate further in your app to perform the action, thereby saving time.

                                        A set of default notification categories is provided by Accengage. If you want to add more categories for interactive notifications, you should call the setCustomCategories: before registering for push notifications:

                                          Note

                                          If you would like to handle custom categories and buttons, you must declare them in the Accengage Dashboard (Settings > Settings > Categories (Buttons)). See our User Guide for more details.

                                          3.2 Handling push delegate callbacks manually

                                          If you choose to disable the automatic integration, by changing the automaticPushDelegateEnabled property of your ACCConfiguration object to NO, you will need to add the following code:
                                          1. Set UNUserNotificationCenter delegate

                                            • Implement the delegates methods

                                              3.3 Carousel Template

                                              Carousel template is a rich notification template so before starting please make sure you are able to receive push with media attachments. If not, please refer to the Media Attachments section.

                                               

                                              To enable the Carousel template in your project, you will need to create a Notification Content 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 carousel template 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.

                                                 


                                                Link the AccengageExtension.framework to your newly created target

                                                 

                                                 

                                                Then, change the newly created NotificationViewController class in such a way that it inherits from ACCNotificationContentViewController and replace the code created by XCode by the following one :

                                                   

                                                   


                                                  In the NotificationViewController scene of the file newly created MainInterface.storyboard file, delete the default Hello world label.

                                                  Finally, in the Info.plist of the extension, update UNNotificationExtensionCategory to acc_carousel_category

                                                   

                                                  3.4 Preventing notification display

                                                  Sometimes, it might be useful to prevent displaying push notifications, for various reasons : avoid displaying push notifications on top of ads, respecting user preferences etc...

                                                  Accengage provides you an option, but don't forget to deactivate it if need be!

                                                  You can prevent the display of any push notification by suspending the Push service :

                                                    Note

                                                    This will not affect In-App messages.

                                                    Silent push notifications

                                                    Silent push notifications improve the user experience by giving you a way to wake up your app periodically so that it can refresh its data in the background.

                                                    To enable silent push in your Xcode project:

                                                    1. In the Project Navigator, select your project.

                                                    2. In the editor, select your iOS app target.

                                                    3. Select the Capabilities tab.

                                                    4. Enable the Background Modes capability.

                                                    5. Enable the Remote notifications background mode. 

                                                    To enable silent push on the Accengage dashboard, tick the content available checkbox when configuring your push message.

                                                    Please bare in mind that APNs treats silent push notifications as low priority and may throttle their delivery altogether if the total number becomes excessive. The actual limits are dynamic and can change based on conditions, but try not to send more than a few notifications per hour.

                                                          

                                                    Section 4 - In app messages

                                                    Have a splashcreen in your app ?

                                                    Allowing a content to be displayed in your splashcreen can affect the inapp behaviour.

                                                    For this reason, a method exists to prevent the display of any Accengage content once the splashcreen is loading. Please check this page for more information (Prevent in-App message display)

                                                    4.1 Basic display

                                                    In-app messages are messages, in various formats, that your application can display while the users are browsing within your application. These messages can be targeted just like Push Notifications, can be triggered in real time based on the user behaviours and their events (see "events" paragraph") and can be displayed in specific parts of your app if need be.

                                                    Their purpose is to stimulate a certain behaviour from your users, as they are probably just a click away from this behaviour, while push notifications primary objective is to drive users back inside the app.

                                                    In-app messages can appear in various formats (banners, interstitials, native alert-box...) and be composed of simple text, or html content.

                                                    You can customize the design of their templates, and you can adapt their content remotely thanks to the Accengage dashboard.

                                                    Once a user clicks on the in-App messages, you can decide of various actions to trigger, such as redirect to a deeplink, a landing page, send an email etc...

                                                     

                                                    The Accengage SDK allows the display of in-App notifications very simply.

                                                    There is no additional code to write to support in-App notifications.

                                                    There are five different default in-App notification templates : 

                                                    • Text Banner : this in-App notification will appear as a view with a height of 50. It will contain a title and a text body. By default this banner will appear at the bottom of the page. The color of the background is black and text is white.
                                                    • WebView Banner : this in-App notification will appear as a view with a height of 50. It will contain a webView that will display the content of a URL. By default this banner will appear at the bottom of the page. The color of the background is black by default.
                                                    • Text Interstitial : this in-App notification will appear in full screen. It will contain a title and a text body.
                                                    • WebView Interstitial : this in-App notification will appear in full screen. It will contain a webView that will display the content of an URL and which will be clickable.
                                                    • WebView interstitial with NavBar : this in-App notification will appear in full screen. It will contain a webView that will display the content of a URL. It also displays a navigation bar and can be browsed.
                                                    • Native Alertbox : this in-App notification is displayed as a native alertbox. It freezes the navigation, and contains, a title, a content, and can propose 1 to X buttons.

                                                     

                                                    If you are wondering how to set up in-App campaigns, please find our tutorial about it.

                                                    4.2 Advanced display customization

                                                     

                                                     

                                                    In the sections below, you will see how to :

                                                    • Customize the behavior and appearance of those in-App notifications
                                                    • Prevent them from being displayed in irrelevant moments (such as splash screen, purchase funnel...)
                                                    • Transmit custom parameters to your app or analytics when these in-App messages are displayed or clicked

                                                    In-app message display customization

                                                    The Accengage SDK lets you customize many aspects of the in-app messages, such as the design, format, size of the templates, their position within a view, the display animation etc...

                                                    Please read the following to craft the best experience for your users.

                                                     

                                                    XIB files

                                                    The In-App Notification views are created using xib files that are provided with the SDK. The content that you will create remotely within the Accengage dashboard (Actions > In-app messages) will be displayed within these views.

                                                    You can modify those xib files (add other elements, change color, font etc...) or preferably add new xib files, as long as you keep the tag info. 

                                                    5 xib files are provided for iPhone retina 3”5 portrait :

                                                    • text notification : BMA4SiPhoneTextNotifView
                                                    • webView notification : BMA4SiPhoneWebViewNotifView
                                                    • Interstitial text notification: BMA4SiPhoneIntersticialTextNotifView
                                                    • Interstitial webView notification: BMA4SiPhoneIntersticialWebViewNotifView
                                                    • Interstitial webView notification (with navBar) : BMA4SiPhoneIntersticialWebViewWithToolBarNotifView

                                                     

                                                    These 5 files are also replicated for :

                                                    • iPhone Landscape :
                                                      • Landscape : with suffix -landscape
                                                    • iPad :
                                                      • Portrait : with suffix -iPad
                                                      • Landscape : with suffix -landscape-iPad

                                                    To choose a custom position of an overlay In-app, add transitions animations and more, you need to set an In-app Notification data source object. Your object must adopt the `BMA4SInAppNotificationDataSource` protocol.

                                                    In-app view edition

                                                    By default the SDK loads the view from the XIB file. You can customize the loaded view programmatically.

                                                    You must not modify the subviews references and tags of the loaded view

                                                     You can also create the inApp view programmatically. To do this you need to respect the following requirements.

                                                     First of all, there are two types of inApp messages : TextMessage & WebMessage . You can check the type by this way :

                                                     

                                                    Here is the list of the required/optional subviews of each message type :

                                                     Required subviewsOptional subviews
                                                    BMA4SInAppTextMessage
                                                    • Text label  :  UILabel  with tag BMA4SInAppOverlayViewBodyTag
                                                    • Close button  :  UIButton  with tag BMA4SInAppOverlayViewCloseTag

                                                    BMA4SInAppWebMessage
                                                    • Web view  :  UIWebView  with tag BMA4SInAppOverlayViewBodyTag
                                                    • Close button : UIButton with tag BMA4SInAppOverlayViewCloseTag

                                                    • Go Back Button : UIButton with tag BMA4SInAppOverlayViewBackTag

                                                    • Go Forward Button : UIButton with tag BMA4SInAppOverlayViewForwardTag

                                                    • Reload Button : UIButton with tag BMA4SInAppOverlayViewReloadTag

                                                    • Stop loading Button : UIButton with tag BMA4SInAppOverlayViewStopTag

                                                    • Open in Safari Button : UIButton with tag BMA4SInAppOverlayViewSafariTag

                                                    • Loader : UIActivityIndicatorView with tag BMA4SInAppOverlayViewActivityTag

                                                    • Toolbar : UIToolbar with tag BMA4SInAppOverlayViewToolbarTag

                                                    Example :

                                                    Changing the default position of an overlay in-app

                                                    By default, in-app banners are displayed at the bottom of the screen.

                                                    Each time the SDK will show an overlay In-app, your data source object will be asked to return a `BMA4SOverlayInAppPosition` option.

                                                    If your data source object returned BMA4SOverlayInAppPositionCustom option, it will be asked to return the origin point of the in-app view.

                                                    Animated transitions 

                                                    By default, the SDK applies a Fadein animation when in-app messages are displayed. You can disable the default animation for a specific in-app message or for all in-app messages by implementing this method : 

                                                    You can also apply custom transition animations by implementing the following methods :

                                                    For more details, please check the BMA4SInAppNotificationDataSource documentation. 

                                                    Full in-app customization

                                                    Accengage dashboard and SDK allow you to create fully customized in-app notifications. This sample shows how to use the custom parameters to achieve this.

                                                    On the SDK side, you can retrieve the parameters using the above mentioned BMA4SInAppNotificationDataSource callback method BMA4SViewForInAppMessage:defaultView:

                                                    The BMA4SInAppMessage object contains the following properties:

                                                    displayCustomParameters - parameters specified on the Accengage dashboard for a specific in-app message

                                                    clickCompletionHandler - block to execute when the user clicks on your custom in-app. You can also pass the button ID as a parameter if it corresponds to your use case.

                                                    displayCompletionHandler - block to execute when your custom in-app is displayed.

                                                    dismissCompletionHandler - block to execute when your custom in-app is dismissed.

                                                    You should only use these properties if you're fully customizing the in-app display. Note that in this case the display rules such as capping and pressure are not managed by the SDK.

                                                     

                                                     

                                                     

                                                     

                                                    4.3 Handling actions

                                                    InAppNotification observers

                                                    You can be notified when the SDK displays or closes an inAppNotification or when a user clicks on it.

                                                     You can add an observer like this :

                                                      Custom parameters

                                                      You can set up in-app messages in the Accengage dashboard so that custom parameters are transmitted to your application when the in-app message is displayed, or clicked.

                                                      This can be useful if you would like to redirect the user to a deeplink, trigger a feature, or if you would like to transmit the information to your analytics.

                                                      You can be notified when the SDK sends data, by adding an observer like this : 

                                                        You can also use the previously mentioned inapp notification observers to extract custom parameters. 

                                                        The custom parameters filled in Accengage Back Office will be present in the userInfo dictionary of the transmitted NSNotification object.


                                                        Prevent in-App message display

                                                        The Accengage SDK will display your in-app message as soon as all conditions you've specified in the Accengage dashboard are met. Therefore it can be useful sometimes to prevent the display of in-App messages, when it is irrelevant, for instance during the splash screen, if an ad is displayed, or if the user is performing a critical action.

                                                        For this reason, the Accengage SDK provides a "Lock" option.

                                                        Be careful always to unlock the In-App message display at the relevant time, as this is a common mistake.

                                                        You can prevent the display of any inApp notification, by calling :


                                                          To reenable the inApp Notifications, you can call : 

                                                            You can enable/disable inApp notifications at any time.

                                                            If you want to lock inapp notifications at startup (while displaying an ad, or during a splash screen for instance), set the lock before launching the SDK.

                                                              This lock does not affect push notifications.

                                                              To activate the locks on push notifications, follow this link : Push notifications .

                                                              Section 5 - Scheduled alarms (local notifications)

                                                              To the user, there is no difference between a local and remote push notification when presented on a given device. Both types of notifications have the same default appearance, which is provided by the system. 

                                                              With local notifications, Accengage SDK configures the notification details locally and passes those details to the system, which then handles the delivery of the notification. With remote push notifications, a server is used to push data to user devices via the Apple Push Notification service. This means that local notifications can be scheduled and delivered to the device even if there's no internet connection which is not the case with remote push notifications. To schedule a local notification even when there's no internet connection, you'll need to mark it as persistent on the Accengage dashboard.

                                                              User permissions are required for local notifications. These are shared between remote push and local notifications so if you are already using push notifications, no additional setup is required. However, if you're not using push notifications, you'll need to register for notifications


                                                              Section 6 - Inbox

                                                              6.1 Basic configuration

                                                              The inbox feature lets you store targeted Inbox messages inside an Inbox within your app, in a similar way that a mailbox stores emails. With this Inbox, your users can retrieve messages over time, browse through the list of inbox messages and interact with them. Inbox messages are a good complement to push notifications or in-app messages.

                                                              These Inbox messages can be a text, a webpage, a landing page, ... with or without buttons.

                                                               

                                                              Note that Inbox messages are independent from Push notifications. You can send Inbox messages which were never sent as Push notifications, and Push notifications will not automatically be displayed in your Inbox.

                                                              Please note that inbox messages are not impacted by the optin/optout system.

                                                              This means that a user can be targeted for inbox messages event if this one is optout to push notification.

                                                              Inside the Accengage dashboard, when setting up a Push notification, there is a shortcut to set up the equivalent of your push as an Inbox message.

                                                               

                                                              The Inbox messages and buttons interact directly with the Accengage SDK.

                                                              You can for instance send a message with a button which will trigger an event, a URL scheme, or display a banner/interstitial when the user clicks on the message.

                                                              With Accengage Inbox you can : 

                                                              • Obtain messages and display them in your own template
                                                              • Update messages status on Accengage Servers (Read/Unread/Archived)
                                                              • Track message events like displaying, opening and button click for statistic purpose

                                                               

                                                              If you don' have access to the Inbox feature on the Accengage Dashboard, please contact our Support Team

                                                              Sample code

                                                              If you want to use this feature, Accengage servers will send all the message information to your app but you will need to create the interface yourself.

                                                              A complete sample project containing an Inbox implementation is available here. You can use it as a starting point and then adapt the interface to your needs.

                                                              Get Messages

                                                              Use the following method to get some messages
                                                              You will need an async callback block to be notified when a message is received. Here is an example of how to define it :

                                                              List Messages

                                                              Now that we have our inbox object filled with messages, we can display them in a UITableView.
                                                              In this example, we will associate a UITableViewCell for each message.

                                                              Do not forget to track the display of your message.

                                                              The callback is called in the main thread, but the process is asynchronous and the callback order is NOT garanteed.
                                                              Double checking the index provided when a message is received is mandatory to avoid errors in your code.

                                                              Message interactions

                                                              Now that we have downloaded and displayed our messages, we will allow our user to interact with them.
                                                              For example, if you display a message in a UITableView, you may want to provide the user with some interaction if he touches a table row.
                                                              You will need to give the message the user interacted with to the SDK.
                                                              According to the message format, the SDK can either start a predefined action or give it back to you to be displayed.

                                                              Do not forget to track the message opening when the user interacts with the message.

                                                              Tracking

                                                              The SDK provides three methods that allow you to track Inbox related events.

                                                              To track the message opening use the following BMA4SInboxMessage method:

                                                              To track the message display use the following BMA4SInboxMessage method:

                                                              To track the button click use the following BMA4SInboxButton method:

                                                              From the version 6.1 of the SDK, you have to track message events manually.

                                                              6.2 Advanced configuration

                                                              Work with Message Buttons

                                                              A message content can have some buttons. Here is an example of how to display and interact with these them.

                                                              Do not forget to track the message button click.

                                                              Update message status

                                                              You can change the status of a message, here is how to do it

                                                              Section 7 - User profile and behaviour tracking

                                                              Tagging relevant information regarding your user profiles and their behaviours is crucial to send personalized and valuable messages.

                                                              Although the Accengage SDK collects by default certain useful information (such as install date, last open date, number of visits, device model ...), it also offers a number of advanced tagging and tracking features for app developers, that will allow you to target notifications, trigger messages at the right time, customize the user experience and analyze your campaign and application performance.

                                                              It is important that you check with the product or marketing team what type of actions they would like to perform, so that you can determine which information needs to be tagged. Most of the time they will provide you with a "tagging plan" which lists all of these.

                                                              However, a strategy could be to first implement a minimal version of Accengage in order to speed up the process and learn faster, then implement the tagging plan at a later stage for more relevant messages.

                                                              In the following section, we will look at the various options that you can enjoy to collect and use the right information:

                                                              • enrich user profile, thanks to custom device information (or User Attributes), which are very useful for targeting and message personalization
                                                              • tag user location, for geolocation targeting
                                                              • tag user behaviours, thanks to events which offer many benefits (targeting, triggering and measurement), as well as views
                                                              • register users to static lists, in order to manage preferences

                                                              If the information you would like to track is inside a webview, please see the Advanced section here

                                                              7.1 User profile

                                                              7.1.1 Enrich User profile with custom device information (or User Attributes)

                                                              In order to send well-targeted and personalized messages, Accengage lets you enrich your user profiles with additional relevant information, called custom device information.

                                                              These are very important for campaign targeting, as well as message personalization.

                                                              For instance, if you tag and update the first name of a user, you will be able to personalize a message with "Hello ${firstname}".

                                                              Traditional usage of custom device information for instance include first name, account ID (to match with external systems), total number of purchases, last purchased product, last purchase date, favorite product... They can be numeric values (set values, or incremental), strings, dates...

                                                              Note

                                                              Unlike events, the values of these custom device info are unique per user. This means the user's associated fields are single-value type fields and each update will erase currently stored values except when it's an incrementation (or decrementation).

                                                              By implementing the library in your app, you will automatically gather certain information about your app users : their device model, OS version, language, country, time zone, app version, install date, the number of visits and more...

                                                              The Accengage library lets you also collect additional custom device information, which can be attached to the user profile through custom database fields.

                                                              If the information you would like to enrich is inside a webview, please see the Advanced section here.

                                                              Important

                                                              Make sure that your custom_field is already created in the database (targeting > database scheme > add a field). Otherwise, the data will be ignored !
                                                              Check our user guide to have an overview of the database associated to your app and how to create a new field.

                                                              To enrich the user profile, and once the database scheme has been updated, you can add additional custom data (or User Attributes) using the updateDeviceInformation:withCompletionHandler: method.

                                                              First, create the device information set:

                                                                Set, delete, increment or decrement the parameters (device information) in a following way:

                                                                  And finally call the appropriate SDK method:

                                                                    7.1.2 User geolocation

                                                                    You can benefit from your user's location data to target them using their past location.

                                                                    The location data are updated when the user opens the application.

                                                                    Note

                                                                    This user geolocation targeting is not to be confused with real-time geofencing which allows for campaign triggering based on real-time geolocation. See Geofence part.

                                                                    To update the user's current location, call the following method with a CLLocation object:

                                                                      7.1.3 Static lists subscriptions

                                                                      With Accengage, you can use two types of segments : Dynamic segments and Static lists.

                                                                      A Dynamic Segment is a segment which is defined by one or more criteria. Therefore, it may change as the values in the database are collected, imported, deleted and modified.

                                                                      A Static List is a set of mobile users whose volume is static at a given time.

                                                                      Unlike a Dynamic Segment whose volume can evolve according to the criteria defined in the interface, a Static List is a set of mobile users whose volume is static at a given time, in order, for example, to be used during a specific campaign or as an exclusion of a dynamic segment. Once created, a Static List can be populated through the SDK.

                                                                      The library provides several methods to manage the subscription to static lists.

                                                                      Important

                                                                      First, make sure that you've created your static list with an external_id. The external_id is required to populate your list through the SDK. To find out more, check out our guide.

                                                                       

                                                                      In order to subscribe a user to a Static List, create an ACCList object :

                                                                        You can also set a subscription expiration date. Once your subscription expires, the user will be removed from the Static List automatically.

                                                                          Add the user to a list or a set of lists :

                                                                            7.1.4 Subscription Tag

                                                                            A device tag has an identifier and a category associated with it. You can also add up to 5 parameters per tag.

                                                                            First, create the tag in a following way:

                                                                              Add some parameters to the tag :

                                                                                The tag can the be set (and later deleted if necessary) in a following way:

                                                                                  Device tag keys are unique therefore you need to use different ones when adding a set of values: 

                                                                                    You can set an expiration date for a device tag using a timestamp: 

                                                                                      Important

                                                                                      Please note that this feature is only available through Accengage's API

                                                                                      For more information please contact our Support Team at http://ticket.accengage.com

                                                                                      7.2 Behaviour tracking

                                                                                      7.2.1 Events tracking

                                                                                      Events are very useful to track user behaviors. One user may have multiple events, and all event occurrences are reported to the Accengage servers.

                                                                                      They can be used for : 

                                                                                      • In-app message or local push real-time triggering
                                                                                      • Application or campaign performance measuring
                                                                                      • Message targeting (subject to your app being integrated in the new platform).

                                                                                       

                                                                                      You will need to ask Accengage teams to activate events, and then you will be autonomous to create them in the Accengage dashboard (in settings > settings > add an event), so as to select them as triggers or targeting options.

                                                                                      Events are composed of a type (a numeric value which categorizes the type of event - see below), and parameters, which brings more information and can be targeted on (provided you are on the new platform).

                                                                                       

                                                                                      The library offers specific and useful methods to track standard events such as "add to cart" events, "purchases" or "leads". You can also track custom events for other user behaviors.

                                                                                      Important

                                                                                      The specified currency for cart and purchase tracking must be compliant with the current link ISO-4217 standard. If not, the tracking will be ignored.

                                                                                       

                                                                                      Add to cart

                                                                                      "Add to cart" events are useful to track and tag the fact that certain items were added to a basket. This is typically useful if you would like to set up "abandoned cart" campaigns, for which you will need to tag "add to cart" events, as well as "purchases".

                                                                                      The library provides a simple method to track items added to a cart. The type of all cart events is 30 but you don't need to specify it. For example, an iPhone 7 added to a new cart, can be tracked with:

                                                                                        If the user adds a new item to the same cart, you should use the same cart_id. For example, if he also adds an iPhone 7 Case to the same cart as the iPhone 7, track it with:


                                                                                          Purchases

                                                                                          "Purchase" events are very useful to tag your user's purchases within your app, to trigger or target messages based on them, but also to measure the revenues generated overall within your app, and thanks to your notification campaigns. Indeed, Accengage provides a statistic dashboard which measures this information (Statistics > advanced statistics).

                                                                                          The library provides a simple method to track purchases. The type of all purchase events is  50 , but you don't need to specify it. It is recommended to specify all the purchased items. For example, the purchase of the previous cart, can be tracked with :


                                                                                            Lead

                                                                                            "Lead" events are useful to track behaviours such as sign-up, registrations etc. The Accengage advanced statistic dashboard will also measure these leads.

                                                                                            The library also provides a simple method to track leads. You might want to track particular special event and action like an authentification. The type of a lead is  10 , but once again you don't need to specify it.

                                                                                            For example, a sign-up event, can be tracked with : 

                                                                                              The total amount is optional when the purchased items are detailed. In this case, the server will calculate it for you. But, if the items set is nil or empty you must specify the total purchase amount.

                                                                                              Important

                                                                                              The purchase_id must be unique. Otherwise, the tracking will be ignored by the server.


                                                                                              Custom events

                                                                                              Apart from the special events seen above, you can tag and track any other event that will be useful for message triggering or targeting, thanks to custom events, such as "clicked on a certain button", "made a search, "invited a friend" etc.

                                                                                              For all of these custom events, use thetrackEvent: method. 

                                                                                              Events types below  1000  are reserved for the library internal usage. You can use custom event types starting from  1001, and you must specify them.

                                                                                              Important

                                                                                              Please note that the length of your concatenated parameters is restricted to 1024 characters : if you exceed this limitation, the SDK will truncate the value.

                                                                                              Create a CustomEventParams object
                                                                                                Add parameters to CustomEventParams object

                                                                                                Four types of parameters are supported : NSString, NSNumber, BOOL and NSDate.

                                                                                                  Track the event

                                                                                                  Finally you can track the event you just created by using the Accengage's class trackEvent method :

                                                                                                    Note

                                                                                                    Each event needs to be defined in the Accengage User Interface. Go to Settings > Advanced Settings, and add a new event of type Custom with the code used in trackEvent method. The label is only used for a display purpose.

                                                                                                    7.2.2 Views

                                                                                                    In order to offer the best user experience, and let you trigger in-app messages at the most relevant time, on the right view (or avoid displaying them on certain views), the Accengage library allows you to track screens or views within your app.

                                                                                                    Unlike events, view tracking is not reported to our servers.

                                                                                                    Don't forget to configure your views in the Accengage dashboard (settings > settings > add a view) to display an understandable label for your product or marketing teams, and so that they can select them.

                                                                                                     

                                                                                                    Note

                                                                                                    We recommend exhaustively tracking every visible view in your app.

                                                                                                     

                                                                                                    The library offers an easy way to track a screen display and dismiss, you just need to import the Accengage.h and set the accengageAlias in the viewDidLoad: method:

                                                                                                      But if you prefer to track screens manually, you'll need to call the method trackScreenDisplay: in the viewDidAppear: method of your controller and the trackScreenDismiss: in viewDidDisappear:.

                                                                                                        7.2.3 States

                                                                                                        States allow you to trigger in-app messages or scheduled alarms. 

                                                                                                        To use this feature, you need to declare the states on Accengage dashboard (Settings > States) and then use them as a trigger.

                                                                                                        To set a state:

                                                                                                          To delete a state:

                                                                                                            7.3 Embedded web content tracking (in-app)

                                                                                                            If your application is hybrid and embeds webviews, you will probably want to tag certain information contained in your webviews.

                                                                                                            In that case, the regular methods of Update Device Information, or Events cannot be used, but tagging these information is possible if you follow the below instructions.

                                                                                                            Note

                                                                                                            In order to activate web content tracking, please contact your Accengage Project Manager for the exact procedure.

                                                                                                            First, follow one of those next steps depending on the component you're using: UIWebView or WKWebView.

                                                                                                            UIWebView

                                                                                                            If you're using the UIWebView component, just replace it with the A4SWebView.

                                                                                                            WKWebView

                                                                                                            If you're using the WKWebView component, you can simply replace it with the ACCWKWebView. But if you prefer avoiding the use of a subclass, you could implement the tracking manually.

                                                                                                            1. Inject the Accengage WKUserScript to your WKUserContentController 

                                                                                                              • Add the handler for the Accengage messages 

                                                                                                                • Initialize your WKWebView

                                                                                                                  • Handle the Accengage messages 

                                                                                                                      Once you've integrated the right component, you can now tag your web content.

                                                                                                                      To do so, follow this documentation.

                                                                                                                      Don't forget, as for regular custom user data or events, to declare them inside the Accengage dashboard.



                                                                                                                    Section 8 - Geofences and iBeacons

                                                                                                                    8.1 Definition

                                                                                                                     

                                                                                                                    With Accengage, you are able to trigger notifications based on your users real-time location, as they enter (or exit) a specific zone, even if the application is closed and the device locked.

                                                                                                                    Real-time notifications based on beacons or geofencing can be setup thanks to Scheduled Alarms or In -App Messages within the Accengage dashboard (Actions > Scheduled Alarms (or In-App messages) > Triggers)

                                                                                                                    Attention

                                                                                                                    This is not to be confused with the user geolocation, which is only tracked when the user launches the application, and which can be used for push notification targeting in the Accengage dashboard (Targeting > Segments/Lists or Targeting > Search).

                                                                                                                    In order to benefit from these features, the Accengage library provides two location-aware technologies : Geofences and iBeacons.

                                                                                                                    To get more information about Geofencing and iBeacons, you can also check out the User Guide.

                                                                                                                     

                                                                                                                    8.2 Permission

                                                                                                                    Geofencing and Beacons are region-based services. Region monitoring requires the Always Authorization access. For more information, please refer to Apple's documentation.

                                                                                                                    Disable the SDK from requesting permission for using location services

                                                                                                                    By default and if needed, when starting one of these services, the library will request permission to use location services. You can prevent the SDK from requesting the needed permission immediately. To do so, call this method before starting the service :

                                                                                                                      If you disable the automated authorization request, you will need to call the method requestAlwaysAuthorization manually, otherwise the service will not be started.

                                                                                                                      Important

                                                                                                                      Add the following keys to your Info.plist: NSLocationAlwaysUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription and describe the reason why the app needs the user’s location information. These keys are required, if not added the system will ignore the request and prevent your app from using location services.

                                                                                                                      Region monitoring (limit the number of regions)

                                                                                                                      You may also limit the number of regions. You may set it from 0 and up to 20 regions.

                                                                                                                        If you don't specify any value, the region count will be set at its maximal value by default (20 regions).


                                                                                                                        8.3 Geofences

                                                                                                                        Geofencing is particularly easy to set up as there is no hardware deployment required. All you need to do is set geofencing areas, which will trigger a message when your mobile users get in or out, even when the app is closed and the device is locked!

                                                                                                                        To start the geofencing service call the following method :

                                                                                                                          8.4 iBeacons

                                                                                                                          The beacon technology enables you to deliver hyper-contextual content based on location, whether it is indoor or outdoor. These small bluetooth proximity sensors communicate with mobile devices to locate users from a few centimeters to a 30-meter radius.

                                                                                                                          Before using the beacon service, make sure that all of your beacon devices share the same UUID.

                                                                                                                          Note

                                                                                                                          Only iBeacon devices are supported. The library doesn't support Eddystone.

                                                                                                                          Start the beacon service

                                                                                                                          To start the beacon service call the following method:

                                                                                                                            Check device compatibility

                                                                                                                            Beacon monitoring requires iOS 7 (or a more recent version of iOS) and at least an iPhone 4S, iPod touch (5th generation), iPad (3rd generation or later), or iPad mini.

                                                                                                                            To check if the user's device can monitor beacons, use the following method:

                                                                                                                              Section 9 - Useful commands

                                                                                                                              Welcome to the useful commands section

                                                                                                                              Here, we suggest you some methods in order to quickly and efficiently perform certain actions within the SDK. 

                                                                                                                              9.1 Activate logging

                                                                                                                              Configure logging application


                                                                                                                              In order to benefit from Accengage support, it is crucial and mandatory that you respect the following steps, which enable you and Accengage to have access to certain infos and logs that will provide valuable context if there is an integration issue.

                                                                                                                               

                                                                                                                              The following configuration is mandatory if Accengage teams need to test the SDK integration. Without it we won't be able to to help you to solve your issues.

                                                                                                                              Accengage provides an application (called ACC Infos) that will in a first hand help you to identify your own device for testing, and in the second hand will provide a contextual logs to the Accengage technical support team during SDK integration, when there is an unexpected behavior.

                                                                                                                              In order to be able to use our application, you will need to:

                                                                                                                              1. add the url schemebma4sreceiver to the scheme whitelist in your application (as explained in the section  "Configure URL Schemes")
                                                                                                                              2. add a localhost exception to the App Transport Security  key in your Info.plist.

                                                                                                                               

                                                                                                                              Enabling console logs

                                                                                                                              Following this step, you will need to activate the library option which turns on logging.

                                                                                                                              These logs help you to better understand the integration of the library and verify if it works as intended. These logs are also mandatory for support team who study problems you may have

                                                                                                                              This is a mandatory step.

                                                                                                                                9.2 Stopping the SDK

                                                                                                                                The following instruction allows you to stop all the SDK services currently running :

                                                                                                                                  Important

                                                                                                                                  The suspension is persistent. If you stop all the SDK services in session A, the suspension will be kept in session B even if the app is relaunched.

                                                                                                                                  9.3 Get the device ID


                                                                                                                                  You may need the device ID. You can get it by using the following instruction from anywhere in your code :

                                                                                                                                    9.4 Disable all network calls

                                                                                                                                      9.5 Check notification provider

                                                                                                                                      To check if the given notification was provided by Accengage servers use the isAccengageNotification: method:

                                                                                                                                        9.6 Get the SDK version

                                                                                                                                        In some case you may need to get programmatically the current Accengage’s SDK version. You can get it by using the following instruction from anywhere in your code :

                                                                                                                                          9.7 Rating and review prompt

                                                                                                                                          In some case you may need to get programmatically the current Accengage’s SDK version. You can get it by using the following instruction from anywhere in your code :

                                                                                                                                            Section 10 - Troubleshooting

                                                                                                                                            10.1 I can't generate my certificate

                                                                                                                                            The .p12 certificate file format is mandatory to enable Accengage to send push notifications. Here is a guide through its generate, renewal and upload on Accengage.

                                                                                                                                            GENERATE A PUSH CERTIFICATE

                                                                                                                                            Here is our guide explaining how to create a push certificate (it needs to be done on a Mac computer).

                                                                                                                                            UPLOAD YOUR PUSH CERTIFICATE ON ACCENGAGE

                                                                                                                                            It needs to be uploaded on the Accengage dashboard in the Application settings : SETTINGS > MANAGE APPLICATIONS > EDIT (The Local Admin rights are required to access this section, if you don't have it please adress your internal Admin or your Project Manager).

                                                                                                                                            10.2 Multiple certificate issues

                                                                                                                                            To avoid multiple certificate issues, you need to correctly generate your .p12 file.

                                                                                                                                            Hereunder the two main errors if you have a multiple certificate :

                                                                                                                                            - Export two certificates in the same .p12 file.

                                                                                                                                            - Export your certificate AND the private / public key in the same .p12 file.

                                                                                                                                            In order to correctly generate your certificate, select only one and just your certificate :

                                                                                                                                            10.3 How the development tokens are generated for an Accengage production app ?

                                                                                                                                            You will find below the explanation about the development token that may be generated on a production application. These can generate issues of push reception.

                                                                                                                                             

                                                                                                                                            When an application has a development provisioning profile and production partners ID, a development token (instead of a production token) will be generated by Apple.

                                                                                                                                            As you have integrated the production partners ID, the device profile will be created in the Accengage production database where only production token are supposed to be generated.

                                                                                                                                             

                                                                                                                                            At each sending push, tokens are analyzed by Apple.

                                                                                                                                            • Tokens which are not related to the certificate are rejected by Apple. Thus they get a feedback (or bounce).
                                                                                                                                            • In addition, these development tokens will disturb the push reception for the following users. Indeed, a development token will block the following users in the database.

                                                                                                                                             

                                                                                                                                            To overcome this behavior, you have to ensure that all the applications for which you integrate our production partners ID have a production provisioning profile.

                                                                                                                                            Moreover, when we notice development tokens during a sending, we have an automatic process to purge the database the night after, and we remove the development tokens which are present in the database.

                                                                                                                                            Please note that even if a purge is made and a user re-opens his/her application (with a development provisioning), a new development token will be automatically re-created for his/her profile.

                                                                                                                                            10.4 I don't find my Device ID (IDFV)

                                                                                                                                            The Device ID (IDFV) is our unique identifier. It allows you to identify for sure the Accengage device profile that represent your own device. In case of test segments it is recommended to use this data as criterion. It is also necessary to get your device information from our application ACCinfos. 

                                                                                                                                            You will find below the methodology in order to recover your IDFV on iOS :

                                                                                                                                            • Download the ACCinfos application by using the link or scanning the following QR :

                                                                                                                                            (QR code available at this address http://sdk.a4.tl/A4SLogReceiver.html)

                                                                                                                                            If the version of your device iOS 9 or higher, you will have to follow this first step :

                                                                                                                                            Go to Settings > General > Device Management or Setting > General > Device Management (iOS11). You will have to approve the application.

                                                                                                                                            This is a new feature since iOS 9, which increases the level of security on enterprise distribution applications.

                                                                                                                                            • Then, open ACCinfos application and minimize it.
                                                                                                                                            • Open your application and let loading. Once you are in the homepage, switch once again on the ACCinfos application.
                                                                                                                                            • You can recover your Device ID on the line IDFV

                                                                                                                                            The following video explain the whole procedure :

                                                                                                                                            Informations about your app are missing in ACCinfos ?

                                                                                                                                            Since iOS 9, Apple has increased security to allow 2 applications communicate each other. If there is no information in our app ACCinfos, it means some steps are still required. Please refer to our technical documentation about this issue : Recover the SDK data from iOS 9


                                                                                                                                            10.5 My device ID does not appear in the application ACCinfos

                                                                                                                                            Since iOS 9, Apple secured the communication between two separate applications. In order to allow our ACCinfos app to retrieve the device ID, the application needs to allow the following steps during the SDK integration :
                                                                                                                                            1. You need to manage ATS exceptions in your Info.plist Documentation here
                                                                                                                                            2. The URL scheme 'bma4sreceiver' needs to be Whitelisted in the app Info.plist Documentation here

                                                                                                                                             

                                                                                                                                            This process is totally secured, its goal is to allow our info App to connect to our SDK and track the device informations related to Accengage.

                                                                                                                                            Note that this activation is mandatory if Accengage needs to test the integration. We strongly recommend it in general in order to allow our technical team to properly investigate in case of unexpected behavior.

                                                                                                                                             

                                                                                                                                             

                                                                                                                                            10.6 My URL scheme does not work

                                                                                                                                            Since iOS 8 in order to be called from external resources the URL schemes need to be whitelisted in the app. If your URL scheme works with push notifications but not on inapp campaigns it could be that the Whitelist has not been done.

                                                                                                                                             

                                                                                                                                            Here are the steps to follow, you can also refer to our technical documentation here 

                                                                                                                                            1. You have to declare your URL scheme of your application.

                                                                                                                                             

                                                                                                                                            For example, the URL scheme is accengage://home, so you have to declare 'accengage'.

                                                                                                                                            To check if it is well declared, you can simply send your URL scheme via Safari:

                                                                                                                                            - If the app opens, it means that the URL scheme is correctly declared.

                                                                                                                                            - Otherwise, it means that the URL scheme is not stated in your application.

                                                                                                                                             

                                                                                                                                            2. You need to add your URL schemes in the whitelist.

                                                                                                                                            Since iOS 9, Apple has implemented additional security to prevent anyone to explore the applications that a user has installed on his device. Therefore, it is now mandatory to report on the whitelist URL scheme used for its implementation.

                                                                                                                                             

                                                                                                                                            3. You need to handle the URL scheme interpretation in your application. (deeplink, browsing, action, etc)

                                                                                                                                            Indeed, when we send a push with an action as URL schema, we transfer this information to the system. Then, your system transfers the information to your application. 

                                                                                                                                            If these 3 criteria are not followed, the URL scheme will be ignored.

                                                                                                                                            10.7 Check the SDK logs using our ACCinfos app

                                                                                                                                            When you open an application that use our SDK, the differents fields in the app ACCinfos are updated to match the application informations. If these informations does not appears you won't be able to receive logs neither.

                                                                                                                                            Informations about your app are missing in ACCinfos ?

                                                                                                                                            Since iOS 9, Apple has increased security to allow 2 applications communicate each other. If there is no information in our app ACCinfos, it means some steps are still required. Please refer to our technical documentation about this issue : Recover the SDK data from iOS 9

                                                                                                                                            Once application informations are visible in ACCinfos application you should be able to display logs in ACCinfos on your device.

                                                                                                                                             

                                                                                                                                            However, by displaying logs on your device you can't use your application at the same time. Most of the time you probably would need to look at your application while displaying logs. With ACCinfos you have the possibility to display logs on an external web browser : just enter the IP address of your mobile device the browser.

                                                                                                                                            Display logs on web browser

                                                                                                                                            The iOS device and the device from which you look at the logs need to be on the same network and the address you have to use is the private one, not visible outside the network.

                                                                                                                                            10.8 I do not receive push notifications

                                                                                                                                            Issues that cause not receiving Push Notifications are very commons. Here are the most recurrent causes :

                                                                                                                                            1. Make sure your Device ID (IDFV) exist in our database.

                                                                                                                                             

                                                                                                                                            Important

                                                                                                                                            If you have uninstalled and reinstalled your app, it is possible your Device ID and/or your Token has changed.

                                                                                                                                             

                                                                                                                                            You can check your device ID by looking at the last open date of your app (see screenshot right below), if it doesn't match, it probably means your device ID changed.

                                                                                                                                            Here is the method to recover your IDFV : IOS: How To Recover Your Device ID (IDFV) On IOS

                                                                                                                                            Please also make sure your segment is correctly targeting your device. For testing purposes, we recommend to target your device ID in your segment. You can also check the number of profiles found for the segment.

                                                                                                                                             

                                                                                                                                            2. Check if your Device is eligible to Push notifications

                                                                                                                                            You can check the following fields in our database by either using our Test Tools or export your device profile.

                                                                                                                                            Token : If there is no Token attached to your device profile, you cannot receive push notifications.

                                                                                                                                            Optin Status: You can check the field 'system_push_optin', if its value is 'N' check if the push are correctly activated for the app.

                                                                                                                                            Feedback field: If the value of the field 'feedback' equals 3 or more, we consider this device profile as uninstalled and we will not target him anymore.

                                                                                                                                             

                                                                                                                                            3. Check your connection, by testing with several wireless networks and 3G / 4G.

                                                                                                                                            If you are using a Wifi connection, it may happen that the Networks blocks some communication. This can block the push notifications reception.

                                                                                                                                             

                                                                                                                                            4. Check the uploaded push certificate for your app (SETTINGS > MANAGE APPLICATIONS)

                                                                                                                                            If the certificate status is "Invalid password", it means that the password registered on the dashboard is not the good one. You have to change it.

                                                                                                                                            If the certificate status is "Connection rejected by iOS gateway", it means that the uploaded certificate is not valid, you have to re-generate it.

                                                                                                                                            The certificate status could also be "Multiple Certificate", it means that the uploaded certificate contains two certificates instead of one.

                                                                                                                                            Here is a link explaining the steps to follow : Multiple Certificates

                                                                                                                                            If this status appears, please verify that the expiration date is not passed, otherwise, you will have to generate a new certificate and upload it on the Accengage dashboard.

                                                                                                                                            In order to have a valid certificate, you should see a green dot as a validation.

                                                                                                                                            If you already have this green dot and you do not receive push, it could be caused by different factors: 

                                                                                                                                                    - Check that the development certificate box is checked if the certificate is used for dev environment.

                                                                                                                                            If you are not using a dev environment, this box should not be checked.

                                                                                                                                                    - Also check that the certificate bundle id matches with the app bundle id on which you make your tests. 

                                                                                                                                                    - Verify that the uploaded certificate is well a push production certificate.

                                                                                                                                                    - Then, verify that the certificate provisioning profile is well linked to the app provisioning profile.

                                                                                                                                             

                                                                                                                                            5. Check the sending summary

                                                                                                                                            You can check the sending summary of the message, it shows the number of notifications we delivered to Apple.

                                                                                                                                            If the sending log shows zero, please check that your segment is actually targeting devices. For your information we target all the device profiles having a token and having the 'feedback' field value < 3. If the sending log is different from zero, the message has well been sent. As a consequence, please check point 4. 

                                                                                                                                             

                                                                                                                                            6. Check the sending environment

                                                                                                                                            Make sure the environment in which you perform your tests on Accengage interface is the good one (DEV / LIVE).

                                                                                                                                             

                                                                                                                                            7. Check the marketing pressure

                                                                                                                                            When you send push and no push is received, check the marketing pressure (SETTINGS > SETTINGS > MARKETING PRESSURE AND DISPLAY DELAY)

                                                                                                                                            In some cases, the sending quota may have already been reached, that could explain why you didn't receive any push notification.

                                                                                                                                             

                                                                                                                                            8. Check the push parameters 

                                                                                                                                            In the messages parameters, we have an option to display or not the push notification "If app is already in the foreground". Please make sure you allow this display if testing while the app is opened.

                                                                                                                                             

                                                                                                                                            9. Check the provisionning profile

                                                                                                                                            The provisionning profile must contain the APNS information. If the provisionning profile has been created before the push certificate, you have to re-create the profile.

                                                                                                                                            10.9 My push action does not work

                                                                                                                                            1. Bad Accengage's SDK Integration

                                                                                                                                            Most of the time, it's about integration problem of our SDK. Try to remove it from your project, and reintegrate it in the most recent version if possible.

                                                                                                                                             

                                                                                                                                            2. Verify settings of your in Accengage's interface

                                                                                                                                            Go in the Settings of you application on our interface.

                                                                                                                                            Verify correspondence between the templates you use in your application and those that are configured in the interface. Check especially the good spelling of different elements in Categories or Custom Params...

                                                                                                                                            10.10 In-app are not displayed

                                                                                                                                            It could happen that sometimes in-app are not displayed on your device. It could be caused for several reasons: 

                                                                                                                                             

                                                                                                                                            1. Verify that the .xib files of the Accengage SDK are well added to the project and to the targets. 

                                                                                                                                            It is the template files which are called when you want to display a banner or an interstitial.

                                                                                                                                             

                                                                                                                                            2. Verify that there is no lock which is integrated on the page in which you want to display the in-app.

                                                                                                                                             

                                                                                                                                            3. Verify your in-app settings on the Accengage dashboard :

                                                                                                                                            - check the capping, perhaps it has been reached already

                                                                                                                                            - check that no other in-app are activated in the same time and with the same priority,

                                                                                                                                            - check that your in-app landing page is well registered on the dashboard, 

                                                                                                                                             

                                                                                                                                            4. Verify if a marketing pressure has been activated for the in-app message.

                                                                                                                                             

                                                                                                                                            5. Verify your connection. Indeed, if your landing page is too heavy, it will take time to be uploaded on your device and a black screen will appear.

                                                                                                                                            10.11 Best practices for iOS 10 Media Attachments

                                                                                                                                            Since the release of iOS 10, it is possible to integrate medias (images, video and audio) in your push notifications.

                                                                                                                                            In terms of technical integration in order to enable the handling of these attachments, here are the available documentations :

                                                                                                                                            User Guide 
                                                                                                                                            Apple extension 
                                                                                                                                            Media attachments 
                                                                                                                                             
                                                                                                                                            This new iOS feature allows a new experience in terms of customization and interaction with your users. However, in order to take the full benefit of it, there are several factors to get aware of and that do not depend on Accengage, but on iOS constraints.

                                                                                                                                             

                                                                                                                                            Indeed, during your tests, if the push is received but not the media, it can be due to these possibilities:
                                                                                                                                            - A bad connection
                                                                                                                                            -  An incompatible with the feature

                                                                                                                                            - A heavy media : your device has failed to display the attachment
                                                                                                                                            - Integration of the iOS 10 extension is incomplete
                                                                                                                                             
                                                                                                                                            Here are the best practices we have noticed during our testing phases of the available functionalities, to be taken into account when integrating the templates with your notifications:

                                                                                                                                            1. Have an iPhone 5S or higher
                                                                                                                                            2. A good internet connection: the reception of your iOS 10 attachement will widely depend on this. The server on your device will attempt to load the template for up to 10 seconds. If it fails, the message will be sent without the attached media.
                                                                                                                                            3. The template should be as light as possible in order to optimize reception. Here are our recommendation for a maximum reach :
                                                                                                                                              • Less than 1MB for an image.
                                                                                                                                              • Less than 1.5MB for a video.
                                                                                                                                              • Less than 1MB for an audio format as well.
                                                                                                                                                 
                                                                                                                                            4. Formats managed by our Dashboard are :
                                                                                                                                              - .jpg, .jpeg, .png, and .gif for templates images.
                                                                                                                                              - .MP3, .MP4, .AIF, and .WAV for audio templates.
                                                                                                                                              - .MPG, .MP2, .MP4, .AVI, .M4A, .M75, .M15 and .VFW for video templates.
                                                                                                                                               
                                                                                                                                            5. Here are media sample we use during our testing phases:
                                                                                                                                              Image 
                                                                                                                                              Video 
                                                                                                                                              Audio

                                                                                                                                            10.12 How to add an image into a push notification ? 

                                                                                                                                             


                                                                                                                                            iOS 10+ supports rich push notifications. On these, you can add images or others medias. To display an icon you simply have to import your desired image when creating your push notification.

                                                                                                                                            It is on the 2nd part "Message Content : Design your push notification and select which actions should be triggered". Just select the template "Picture" and import your image file :

                                                                                                                                            About the icon

                                                                                                                                            Currently on iOS 11 it is not possible to resize or change image aspect ratio of this thumbnail. Some native iOS application may, however, have larger icons.


                                                                                                                                            10.13 What are the options that you need to check when you submit an application using the IDFA ?

                                                                                                                                            On April 11th 2014, Apple updated its guidelines about the submission of applications that use IDFA.

                                                                                                                                            If you enabled tracking within our SDK, you need to quote the related category while submitting the app to the Store.

                                                                                                                                            On the drop down that will appear, you need to check the following options :

                                                                                                                                            10.14 Devices model technical naming convention

                                                                                                                                            In the device database, the 'Device model' field is automatically tracking the technical Id of the device model on iOS. It looks like 6.2, 7.2 ...

                                                                                                                                             

                                                                                                                                            In order to make the matching with the names of these device models here is a listing with the references : https://www.theiphonewiki.com/wiki/Models 

                                                                                                                                            10.15 How to make a deeplink for a path in a mapping application ?

                                                                                                                                            If you want to use a deeplink referring to a pre-selected path in a mapping application, here are the different URL to use:

                                                                                                                                            - Maps (only available on a geofence trigger):http://maps.apple.com/?saddr=#{deviceLat},#{deviceLong}&daddr=#{targetLat},#{targetLong}

                                                                                                                                            - Google maps (for ones who have the application):

                                                                                                                                            • Address : comgooglemaps://?daddr=Accengage,+31+rue+du+quatre+septembre,+Paris
                                                                                                                                            • GPS coordinates: comgooglemaps://?daddr=latitude,longitude

                                                                                                                                            You will have to choose the action URL scheme for in-app or browser for push.

                                                                                                                                            Note that when you use spaces in your URL, you have to replace them by "+".

                                                                                                                                            You can also refer to the Official Apple documentation explaining the native deeplinks in more details.

                                                                                                                                            10.16 I can't add a password to my certificate 


                                                                                                                                            To begin with, ensure you already requested your appropriate certificate on the Apple developers interface.

                                                                                                                                            https://developer.apple.com/account/ios/certificate/

                                                                                                                                            (See our documentation to request the certificate).

                                                                                                                                            Once you created your certificate you may download it as .cer file.

                                                                                                                                            Double click the downloaded file to add it to your Keychain.

                                                                                                                                            How to access to the Keychain tool ?

                                                                                                                                            You may access to the Keychain Access tool in utilitaries -> keychain access

                                                                                                                                            Right click on the certificate in the Keychain access and export it as a .p12 file.

                                                                                                                                            What is .p12 files ?

                                                                                                                                            .p12 is the certificate file format you need to build and publish your app on the Apple App Store.

                                                                                                                                            Finally, save the .p12 certificate and enter your password in the prompt meant for that purpose :


                                                                                                                                             


                                                                                                                                            10.17 I don't find my Bundle ID 

                                                                                                                                            There are multiple way to get the Bundle ID of your application. 

                                                                                                                                            In Xcode

                                                                                                                                            You also could get your Bundle ID in Xcode.

                                                                                                                                            You just have to select your project target. The bundle is written in the "Identity" section as shown on the following screenshot :

                                                                                                                                            iTunes Connect

                                                                                                                                            Bundle ID is also available on Apple Developer's interface (iTunes Connect, tab "App Store").

                                                                                                                                             

                                                                                                                                            You could also get it by using the ACCinfos application

                                                                                                                                            Take a look on this article, : 10.4 I don't find my Device ID (IDFV) . You will see the Bundle ID on the second line (under Application name)

                                                                                                                                            • No labels