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 ~580 Ko.

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:

       

       


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

            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. (set the deployment target to iOS 10.0)

             

             

            1. Once your notification service is created, download and unzip the latest version of the iOS SDK Extension.
            2. 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.



            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 AccengageExtension.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.
            6. Inherit from ACCNotificationServiceExtension in NotificationService and delete all the code generated by XCode.

              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

                       

                      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. 

                      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

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

                          Note

                          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.

                            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.

                              3.3 Carousel Template

                              Carousel template is a rich notification template so before starting please make sure that you've followed all the steps explained in the Media Attachments section.

                               

                              To add the template to your project:

                              1. Add a iOS target and choose Notification Content Extension from the list
                              2. Add a product name and click on finish
                              3. Activate the target when prompted



                              4. Link the AccengageExtension.framework to your newly created target 

                              5. Make sure that the deployment target for your content extension is set to 10.0
                              6. Change the newly created NotificationViewController class so that it inherits from ACCNotificationContentViewController and delete all the dummy code and storyboard's view controller contents.


                                • In the NotificationViewController scene of the storyboard, delete the default "Hello world" label

                                • In the Info.plist, update UNNotificationExtensionCategory to acc_carousel_category

                                 

                                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

                                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.

                                 

                                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

                                 

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

                                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

                                4.2 Advanced display customization

                                 

                                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

                                BMA4SInAppNotificationDataSource

                                 

                                 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. 

                                 

                                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 Device Tags

                                                        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:

                                                              7.1.5 Rating and review prompt

                                                              This feature allows the users to rate and review applications without ever having to leave the app.

                                                              Preview popup notation

                                                              The feature is available on iOS 10.3 and above.

                                                              Important

                                                              The notation popup can be displayed only 3 times per application and per year. Make sure to read carefully the Apple documentation before using the feature.


                                                              In order to display the prompt, you'll need to add the parameter "accrating" to your URL Scheme template. Parameters string must begin with a "?" and parameters should be separated by a "&".

                                                               

                                                              Example of valid URL Scheme : your_app://your_page?accrating


                                                              You can ask the Accengage SDK to display the prompt in the following cases:

                                                               

                                                              • The URL associated with the Push action
                                                              • The URLs associated with the interactive Push button actions
                                                              • The URLs and redirections loaded in web In-App content
                                                              • The URLs associated with In-App actions
                                                              • The URLs associated with Inbox message actions
                                                              • Incoming URLs handled by the application:openURL:sourceApplication:annotation: or application:openURL:options: method of your AppDelegate.

                                                              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 :

                                                                                                                  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