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.

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.

Requirements & important information on the 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).

Configure push notifications

Push notifications allow an app that isn’t running in the foreground to notify its users of relevant information. Push notifications enable you to send relevant content that you manage, and to whom you wish, from a remote notification server (Accengage) which communicates with the Apple Push Notification service (APNs) that then delivers it to your application users on their devices.

To ensure a good SDK integration and a smooth development experience, there are a few important steps
that you need to take.

First, you enable push notifications in the Xcode project. Xcode adds the APNs entitlement to your project and the App ID. If necessary, Xcode creates an explicit App ID based on the bundle ID, and for development, an Xcode managed team provisioning profile containing the App ID.

After you enable push notifications, generate and export a TLS certificate.

 

Enable Push Notifications in your Xcode project

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

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, so please make sure you always respect this!

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

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

 

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.

Configure logging

Configure logging application

Accengage provide an application to help your team to identify for sure their device profile among the others, which is helpful for push notifications tests. It also allows our technical team to properly investigate in case of unexpected behavior. We strongly recommend it.

Note

This configuration is mandatory if Accengage teams need to test the SDK integration.

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

  1. add the scheme bma4sreceiver to the schemes withelist as explained in the previous section
  2. add a localhost exception to the App Transport Security  key in your Info.plist.

 

Enabling console logs

For diagnostic purposes, the library contains an option that turns on logging. These logs allow you to gain more insight on the library's integration and ensure it's working as expected. These logs can also be helpful for support staff who are troubleshooting problems.

    Sample application

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

    Install and start the SDK

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

    Installation

       

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

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

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

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

      4. Install the SDK

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


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

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

      2.  Add the Accengage SDK to your Cartfile:

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

      3. Execute the following command in your Cartfile directory:

       

      This steps explains how to manually install the SDK.

       

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



      3. In your application target you need to add a Copy Files build phase to your target. From the Build Phases panel of your target's configuration:
        1. Press the + button from the top left region
        2. Select New Copy Files Phase. A new entry will appear in the Build Phases list.
        3. Change the destination selector to Frameworks
        4. Find the Accengage.framework and drag it into this new section.



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



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

       

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

       

      Configuration file

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

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

      Import

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

        Initialization

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

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

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

          You can also programmatically override the configuration values:

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

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

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

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

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

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

                    or:

                      Customize the starting 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.

                      Don't forget to delete the AccengageConfig.plist file if you're not using it to start the SDK

                      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

                      If you want the library to be more respectful of users privacy, you can choose the restricted tracking mode.

                      Note that if you use the restricted mode, some advanced targeting features may not be available. This is not needed 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.

                       

                      Crash monitoring

                      In order to enhance and monitor its quality of service, Accengage has implemented a feature to detect app crashes and quantify any suspicious surge.

                      The goal is for our support to be very reactive in case of any issue affecting our SDKs.

                      Accengage provides a method to disable this feature if you do not want Accengage to be notified.

                      Important

                      In case you are using a crash-monitoring tool, this feature may in some cases alter the functioning of your crash-monitoring tool.

                      For this reason, Accengage provides a possibility to disable the feature.

                      Note

                      This feature is just to monitor internally the quality of service.

                      Accengage does not provide a dashboard or bug tracking capability.

                       

                      In case you would like to disable this feature, please set the value of the crashReportingEnabled parameter (in your ACCConfiguration object) to NO

                      Delay SDK launch

                      To delay the launch of the SDK, you'll need to set the launchOptions property of the ACCConfiguration object (passing the launchOptions dictionary of the didFinishLaunchingWithOptions method).  

                      Push

                      The library provides a simple interface to manage the push service.

                       

                      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.

                        When called, this method 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.

                          Handling

                          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

                              Media attachments

                               iOS 10 introduces support for rich notifications, it adds the ability to send push notifications with media attachments such as images, sounds and videos.

                              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.

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

                                   

                                  Notifications custom parameters

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

                                    Advanced Push

                                    Check notification provider

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

                                      Custom notification sounds

                                      You can specify a custom sound that iOS plays when it presents 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.

                                      Note

                                      Prefer a short file name.

                                      Preventing notifications display

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

                                        Note

                                        This will not affect In-App messages.

                                        Badges

                                        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. 

                                              Tracking

                                              The library offers a number of advanced tracking features for iOS developers that allow you to trigger In-App messages depending on your user’s behavior.

                                              For example, you can track:

                                              • purchases
                                              • abandoned carts
                                              • user registrations
                                              • screens

                                              Events

                                              The library offers an easy way to track standard events like: add to cart events,  purchases or leads. You can also track custom events for other user behaviors. Triggered events will be reported to our servers.

                                              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

                                              The library provides a simple method to track items added to a cart. The type of all cart events is 30. 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

                                                  The library also provides a simple method to track purchases. The type of all purchase events is 50. It is recommended to specify all the purchased items. For example, the purchase of the previous cart, 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.

                                                    Lead

                                                    You might want to track particular special event and action like an authentification. The type of a lead is 10. For example, a sign-up event, can be tracked with:

                                                      Custom event

                                                      For all other types of events, use the trackEvent: method. Events types below 1000 are reserved for the library internal usage.  You can use custom event types starting from 1001

                                                      Important

                                                      To use the additional parameters of the custom events for targeting purposes, they must formatted as a valid JSON string. Only strings are accepted as key. For the value, only strings, numbers and booleans are accepted. Use a timestamp to represent a date.

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

                                                        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.

                                                        Views

                                                        Track screens or views within your app so you can trigger messages on specific views or avoid message display on others. Unlike Events, view tracking is not reported to our servers.

                                                         

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

                                                            User profile

                                                            By implementing the library in your app, you will automatically gather information about every single one of your app users: device model, OS version, language, country, time zone, app version, install date, the number of visits and more. You can also collect additional custom information.

                                                            All collected information can be used for targeting and personalization purposes.

                                                            Note

                                                            The user's associated fields are single-value type fields. Each update will erase currently stored values except when it's an incrementation (or decrementation).

                                                            Custom fields

                                                            In addition to the information collected by the library, you can enrich your user's information with additional customized data. To do so, use the updateDeviceInfo: method.

                                                              Important

                                                              Make sure that your custom_field is already created in the database. Otherwise, the data will be ignored.
                                                              Check our user guide to have an overview of your app's associated database and how to create a new field.

                                                              Update date-type data

                                                              To update date-type fields, you should format your date object in yyyy-MM-dd HH:mm:ss zzz string. The library provides a helper. Use the normalizedStringForDate: method to format your date objects.

                                                                Update counter-type data

                                                                To update counter-type data, you can increment (or decrement) your field by prefixing the value with the positive sign + (or negative -).

                                                                  Update fields from an URL

                                                                  In addition to the native updateDeviceInfo: method, the library parses the URLs in the following cases and triggers the updateDeviceInfo: method if you've added the needed parameters to your URL query.

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

                                                                  In the last case, make sure that you have already created a custom URL scheme as explained in this section and added the following method implementations to your AppDelegate:

                                                                  Uncomment the handleOpenURL: call if you've disabled the automatic integration.

                                                                    If your app supports Universal Links also add:

                                                                      Now you're ready to update fields using URLs. To do so, add a bma4sudi to your URL query with a JSON encoded string. For example, to update the field custom_field with the value new_value:

                                                                      1. Create a JSON object: {"custom_field":"new_value"}
                                                                      2. URL Encode it: %7B%22custom_field%22%3A%22new_value%22%7D
                                                                      3. Add the bma4sudi key to your URL query with the encoded string as value ...?bma4sudi=%7B%22custom_field%22%3A%22new_value%22%7D

                                                                       

                                                                      User location

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

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

                                                                        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. It is, therefore, liable to change as the values in the database are collected, imported, deleted and modified.

                                                                        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.

                                                                        Subscribe to a list

                                                                        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 automatically removed from the static list.

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

                                                                              Unsubscribe from list

                                                                              As for a subscription, first create an ACCList object then you can remove the user from the list: 

                                                                                Get a subscription status

                                                                                To check if the user is currently added to a list (or set of lists), call the following method with a set of ACCList objects: 

                                                                                  Get the list subscriptions

                                                                                  You can also retrieve all the user's subscriptions. To do so:

                                                                                    In-App messaging

                                                                                    The SDK also allows the display of inApp notifications. There is no additional code to write to support inApp notifications.
                                                                                    There are five different inApp notifications :

                                                                                    • Text Banner: an InApp notification that will appear as a view with a height of 50. It will contain a title and a text body.
                                                                                    • WebView Banner: an InApp notification that will appear as a view with a height of 50. It will contain a webView that will display the content of an URL.
                                                                                    • Text Interstitial which will appear in full screen. It will contain a title and a text body.
                                                                                    • WebView Interstitial: which 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: which will appear in full screen. It will contain a webView that will display the content of an url. It also displays a navigation bar and can be browsed.

                                                                                    You can customize the behavior and appearance of those inApp notifications.

                                                                                    For more details, please check the section below.
                                                                                    If you are wondering how to create an in-app, please find  our tutorial about it.

                                                                                    Notification display customization

                                                                                    XIB files

                                                                                    The InApp Notification views are created using xib file that are provided with the sdk. You can modify those xib files (add other elements, change color, font etc), 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

                                                                                    Those 5 files are also declined for :

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

                                                                                    Advanced 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 NIB file. You can custom the loaded view programmatically.

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

                                                                                         

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

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

                                                                                         

                                                                                           

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

                                                                                           

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

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

                                                                                          • Go Back Button : UIButton with tag BMA4SInAppOverlayViewBackTag

                                                                                          • Go Forward Button : UIButton with tag BMA4SInAppOverlayViewForwardTag

                                                                                          • Reload Button : UIButton with tag BMA4SInAppOverlayViewReloadTag

                                                                                          • Stop loading Button : UIButton with tag BMA4SInAppOverlayViewStopTag

                                                                                          • Open in Safari Button : UIButton with tag BMA4SInAppOverlayViewSafariTag

                                                                                          • Loader : UIActivityIndicatorView with tag BMA4SInAppOverlayViewActivityTag

                                                                                          • Toolbar : UIToolbar with tag BMA4SInAppOverlayViewToolbarTag

                                                                                          Example :

                                                                                           

                                                                                            Changing the default position of an overlay in-app

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

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

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

                                                                                                Animate transitions 

                                                                                                By default, the SDK apply FadeIn animation. You can disable the default animation for a specific or for all in-app messages by implementing this method: 

                                                                                                  You can also apply a custom transitions animations by implementing the flowing methods : 

                                                                                                     

                                                                                                    For more details, please check the BMA4SInAppNotificationDataSource documentation. 

                                                                                                    Prevent inApp notifications display

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

                                                                                                       

                                                                                                      This is useful if you display some ad at the launching time.
                                                                                                      To reenable the inApp Notifications, you can call : 

                                                                                                         

                                                                                                        You can enable/disable inApp notifications at any time.

                                                                                                        If you want to lock notification at startup (while displaying an ad for instance), set the lock before launching the tracking.

                                                                                                          This lock does not affect push notifications. 
                                                                                                          To activate the locks on push notifications, follow this link: Push notifications.

                                                                                                          InAppNotification observers / Add custom parameters to in-App messages

                                                                                                          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 :

                                                                                                            Data Receiver

                                                                                                            You can be notified when the sdk sends data.
                                                                                                            You can add an observer like this : 

                                                                                                             

                                                                                                              The custom parameters filled in Accengage Back Office will be present in NSNotification userInfo dictionary.


                                                                                                              Inbox

                                                                                                              The inbox feature was made to display some delayed messages to your users. These messages can be a text, a webpage, a richpush, ... with or without buttons.

                                                                                                              These messages and buttons interact directly with the Accengage SDK.
                                                                                                              You can for instance send a message with an event button, trigger a URL scheme, or display a banner/interstitial when the user opens a message.
                                                                                                              Indeed, with this feature, the user can browse all of the messages you sent to him before.
                                                                                                              The inbox can be used as a reminder or as a lite mail client in order to communicate with your clients.

                                                                                                              If you want to use this feature, Accengage servers will send all the messages information to your app, but you will need to handle yourself the display part.

                                                                                                              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

                                                                                                              You can find a complete example in our sample project.

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

                                                                                                              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.

                                                                                                              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

                                                                                                              Beacons & Geofencing

                                                                                                              Take advantage of geolocation to broadcast messages based on users' real-time location data. To do so, the library provides two location-aware technologies: Geofencing and Beacons.

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

                                                                                                              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 authorization. To do so, call this method before starting the service:

                                                                                                                If you disable the automated authorization request, you will need to 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.

                                                                                                                Geofencing

                                                                                                                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:

                                                                                                                  Beacons

                                                                                                                  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:

                                                                                                                      Advanced

                                                                                                                      Embedded web content tracking

                                                                                                                      Note

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

                                                                                                                      Once you've integrated the right component, you will have to tag your web content. To do so, follow this documentation. But 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 

                                                                                                                              Get the device ID

                                                                                                                                Stop all services

                                                                                                                                  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.

                                                                                                                                  Disable all network calls

                                                                                                                                    Get the version

                                                                                                                                      How to 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)

                                                                                                                                      I want to add a password to my .p12 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 :


                                                                                                                                       


                                                                                                                                      SDK Size

                                                                                                                                      The SDK will increase your app download size by ~580 Ko

                                                                                                                                      • No labels