image


indigitall Phonegap/Cordova SDK


Contents

  1. Introduction
    1. Obtaining the Indigitall´s SDK
      1. Download the SDK from the indigitall server
    2. Obtaining the application´s App Token
    3. Obtaining the .cer and .p12 from the APNS
    4. Obtaining the application´s Sender ID and Api Keys
  2. Integration
    1. Indigitall´s SDK
    2. iOS Settings
    3. Android Settings
  3. Using the library
    1. Initializing the library
    2. Available library functions
    3. Push messages
    4. Geolocated push messages
      1. Enable service for IOS
    5. External Apps Service
      1. Enable service for IOS
      2. Enable service for Android
    6. Get DeviceID
    7. Notifications with images in iOS 10
    8. App Group configuration for iOS
  4. Implementation Updates
    1. Update to 4.0 from older sdk version
  5. F.A.Q
  6. Contact

1. Introduction

This document shows all the information needed to carry out the integration of the Indigitall SDK into an application developed with the PhoneGap framework, for devices with the Android and iOS operating system. The same shows everything that is needed to integrate the SDK into an existing application in order to use the services offered by the Indigitall platform.

It is important to consult this manual before carrying out the development, and follow all the steps indicated therein, to ensure the proper operation of the integration. As this document is intended for PhoneGap developers, a technical language will be used and examples of a source code will be shown when necessary.

1.1. Obtaining the Indigitall´s SDK

The indigitall SDK can be get and integrate by two ways:

  • From indigitall server: The SDK must be downloaded from indigitall server and must be added to the proyect indicanding its path.

  • From oficial repository: The SDK must not be downloaded, only has to be added to the proyect with the name indigitall.

1.1.1 Download the SDK from the indigitall server

The SDK can be obtained from the following link: indigitall SDK for Phonegap

You need to have an identifier so that the app, in which you want to integrate the SDK, can carry out the communication with the Indigitall environment. To receive this identifier, the developer must provide Indigitall with the necessary data to send the notifications (.cer and .p12) obtained from the console for Apple developers in the case of iOS and (Sender ID and Api Key) obtained from the GCM (Google Cloud Messaging) tool or Google’s FCM (Firebase Cloud Messaging) in the case of Android.

1.2 Obtaining the application´s App Token

Every application registered in the Indigitall’s Control Panel will have a unique identifier called App Token. This identifier will be used to initialize the SDK and will be responsible for linking the application to the Indigitall platform, thus it will indicate, to which application the notifications that come to the device belong. The application’s App Token can be obtained from the Indigitall’s Control Panel by an Administrator user in the "Details" section of the application.

1.3 Obtaining the .cer and .p12 from the APNS

To be able to send push notifications to iOS devices, you need to have some certificates that allow the APNS (Apple Push Notification Service) communication.

For that, the corresponding certificates will have to be generated (.cer, .p12 and password, if it has one) and send them to Indigitall.

The following tutorial explains how to get these certificates.

Obtain ".cer"and ".p12"certificates from APNS

1.4 Obtaining the application´s Sender ID and Api Keys

Previously, the identifiers called Sender ID and Api Key were needed for the application to receive notifications with the GCM Google tool. At present, with the new Google FCM tool, these parameters are called "Sender ID" and "Server Key", although we will continue to call them Sender ID and Api Key to make it easier for the users who already have from GCM.

These identifiers will be used in the SDK to connect the Google's GCM/FCM tool to the devices that install the application. You can see how to get them in these links:

Obtain the Sender ID and Api Key in GCM (Google Cloud Messaging)

Obtain the Sender ID and Api Key in FCM (Firebase Cloud Messaging)

2. Integration

2.1 Indigitall´s SDK

The Indigitall library consists of a Phonegap plugin (plugin folder/) that collects the Android and iOS SDKs and makes them useful to be called from javascript.

To integrate the plugin, you must execute the following command in the console being in the directory app/:

  • If the SDK was downloaded from indigitall server:

    phonegap plugin add {route_to_the_plugin_directory}
  • If the SDK was downloaded from oficial repository:

    phonegap plugin add indigitall

NOTE: To eliminate the plugin of the sdk version 3.2, you must execute the following command in the console being in the directory app/:

phonegap plugin remove indigitall

2.2 iOS Settings

For can use the indigitall library in IOS, the keys indigitallAppToken, indigitallThirdParty and indigitallAppGroup must be added in the *-Info.plist project file.

You can do this directly in the *-Info.plist file or from Phonegap, adding the following code lines:

<platform name="ios">
    ...
    <config-file parent="indigitallAppToken" target="*-Info.plist">
        <string>YOUR_APP_TOKEN</string>
    </config-file>
    <config-file parent="indigitallThirdParty" target="*-Info.plist">
        <false />
    </config-file>
    <config-file parent="indigitallAppGroup" target="*-Info.plist">
        <string>YOUR_APP_GROUP</string>
    </config-file>
</platform>

2.3 Android Settings

  • Archivo google-services.json

To download the app configuration file , you have to follow the next steps:

  1. Enter in the Firebase Console and open your project.
  2. Press in the settings icon and select "Configuration project".

    project_configuration

  3. Add your app to Firebase, From "General" tab press in the button that is shown in the next image:

    add_firebase

  4. Register the app in the Firebase. You have to set the app packet name and the SHA-1 sign (optional) and press in "Register App".

    register_app

  5. Download the google-services.json:

    download_json

Once you have the google-services.json, you must add the file in the root of your Phonegap project.

When the google-services.json file is added is necessary link it in the config.xml of yout Phonegap project:

<platform name="android">
       <resource-file src="google-services.json" target="/google-services.json" />
   </platform>
  • build.gradle file of the plugin

To be able to use the Indigitall’s library in Android, the project must be configured so that the Android’s version of the compilation used is the 6.0. This includes the following libraries:

  • Android v4 support library in its 26.1.0 version.
  • Firebase library in its 15.0.0 version('firebase-location' module)
  • Google Play Services library in its 15.0.0 version ('location' module).
  • Okhttp Square library in its 3.6.0 version.
  • Picasso Square library in its 2.71828 version.

So that the file is configured with the next libraries:

dependencies {
    implementation 'net.indigitall:pushsdk:4.0.+'

    implementation 'com.android.support:support-v4:26.1.0'
    implementation 'com.google.firebase:firebase-messaging:15.0.0'
    implementation 'com.google.android.gms:play-services-location:15.0.0'
    implementation 'com.squareup.okhttp3:okhttp:3.6.0'
    implementation 'com.squareup.picasso:picasso:2.71828'
}
apply plugin: 'com.google.gms.google-services'

If your project already includes any of these libraries, you can comment their respective lines in the build.gradle file in the plugin’s route /plugin/src/android/build.gradle for them to not give any type of conflict.

  • AndroidManifest.xml file of nativeProject

Also several optional permissions must be added in the AndroidManifest.xml of the Android native project, if geolocated pushes and clickToCall pushes want to be used:

...
<!-- Optional Permission -->

<!-- Location Permissions-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!--Phone Permission-->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.CALL_PHONE"/>
...

3. Using the library

To be able to use the library, you need to have the Indigitall’s APP_TOKEN for the application and register it in the Google's GCM/FCM service to obtain the API_KEY and the SENDER_ID and enable it to receive push in the console for Apple developers to obtain the .cer and .p12 certificates.

3.1 Initializing the library

The following code must be included in the deviceready event to initialize the library:

var options = {
  senderID: “SENDER_ID”,
  apptoken: “APP_TOKEN”,
  useExternalApps: false,
  pushIcon: “ic_launcher”,
  smallIcon: “ic_launcher_mono”,
  smallIconColor: “#FF6600”
};

window.plugins.indigitall.init(options);
window.plugins.indigitall.initStats();

The fields within options must be modified to fit the application. They are the following:

  • senderID: the application’s senderID obtained from GCM/FCM. See corresponding section.
  • appToken: unique application identifier provided by Indigitall.
  • useExternalApps:set to true in case of using this functionality.
  • pushIcon: application’s icon for Android notifications.
  • smallIcon: monochrome icon for Android 5.0 notifications or later ones.
  • smallIconColor: color of the monochrome icon. This field is optional.

NOTE: In Android case, the icon images must be added to directory /drawable.

3.2 Available library functions

Indigitall provides some methods for that the applications use the library. This methods offer serveral funtionalities that go from let subscribe and manage the tags to operations to enable and disable the device.

The tags have to be created in the panel previously to can be listed and the user can subscribe or unsuscribe of them.

The available methods in the indigitall class are the next:

/**
  * Check the status of the device to know whether or not it receives notifications.
  */
isDeviceEnabled(success:function, fail:function);

/**
  * Enable the device for notifications to arrive.
  */
enableDevice(tags:array, success:function, fail:function);

/**
  * Disable the device so that notifications do not arrive.
  */
disableDevice(tags:array, success:function, fail:function);

/**
* Check if the SDK is enabled or disabled to send the location.
*/
isLocationEnabled(success:function, fail:function);

/**
* Enable the SDK to send the location.
*/
 enableLocation(function:success, function:fail);

/**
* Disable the SDK to not send the location.
*/
disableLocation(function:success, function:fail);

/**
  * Ask for the list of tags created in the panel.
  */
fetchAllTags(success:function, fail:function);

/**
  * Ask for the list of tags to which the device is subscribed.
  */
fetchSubscribedTags(success:function, fail:function);

/**
  * Subscribe the device to a list of tags.
  */
subscribe(tags:array, success:function, fail:function);

/**
  * Unsuscribe the device to a list of tags.
  */
unsuscribe(tags:array, success:function, fail:function);

/**
  * Return the unique Indigitall identifier per device.
  */
getDeviceiD(success:function, fail:function);

3.3 Push messages

Once we have completed the registration and initialization process, the application is ready to receive push messages, the library will handle the messages and display the appropriate notifications. The application will be able to collect data from the push messages when "Open App" notifications are sent.

It is necessary to control when the app goes to background, to foreground and when it is open to correctly collect the push. It is best to use resume and pause events.

The way to collect this data would be as follows:

/* Control when the app goes to Foreground */
document.addEventListener(‘resume’, function() {
        window.plugins.indigitall.enterForeground(successCallback,errorCallback);
        window.plugins.indigitall.getUri(function(data) {
                console.log ("Notification received. Indigitall parameter:" + data);
        }, function() {
                console.log ("Notification received. Does not belong to Indigitall");
        });
}, false);

/* Control when the app goes to Background */
document.addEventListener(‘pause’, function() {
        window.plugins.indigitall.enterBackground (successCallback,errorCallback);
}, false);

/* Control when the app is open and a push comes (only iOS) */
document.addEventListener (‘foregroundpush’, function(push) {
        console.log ("Notification received. Indigitall parameter:" + push.data);
}, false);

3.4 Geolocated Push Messages

For the use of Geofences and geolocated pushes, is necessary that the application has the location permissions approved by the device user.

In Android case, the permissions are asked when the used open for the first time the application after the install it.

In the IOS case, for give support all versions of S.O, some changes are made when the permissions are asked. This changes are explained in the next point.

3.4.1 Enable service for iOS

For can use the Location service is necessary make the next changes in the *-Info.plist file:

  • Add three new keys of String type with the corresponding messages, that will be shown to the user in each case:

      Privacy - Location Always Usage Description
      Privacy - Location Always and When In Use Usage Description
      Privacy - Location When In Use Usage Description
    

The *-Info.plist file would be configured like this:

<platform name="ios">
    ...
    <config-file parent="Privacy - Location Always Usage Description" target="*-Info.plist">
        <string>Can we use your location always?</string>
    </config-file>
    <config-file parent="Privacy - Location Always and When In Use Usage Description" target="*-Info.plist">
        <string>Can we use your location always?</string>
    </config-file>
    <config-file parent="Privacy - Location When In Use Usage Description" target="*-Info.plist">
        <string>Can we use your location when you use the application?</string>
    </config-file>
    ...
</platform>

3.4.2 Enable service for ANDROID

For can use the Localización service is necessary add the next permissions to AndroidManifest.xml file of native Android project:

...
<!-- Optional Permission -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
...

3.5 External Apps Service

The External Apps service lets send notifications depending on the user has or has not installed one or more than one applications. The applications that want to be checked, must be specified in the panel.

3.5.1 Enable service for iOS

For can use the service externalApps is necessary make the next changes in the *-Info.plist file:

  • Put the key indigitallThirdParty to true. This key let enable the service.

  • Add a new key of type Array LSApplicationQueriesSchemes whose item will be Strings whith the URL Schemes of the apps that want to be checked in the service. With this array we indicate which will be the applications that we desire the user has installed to send him pushes.

    The *-Info.plist file should be configured by the next way if we want to check Facebook application like externalApp :

    <platform name="ios">
        ...
        <config-file parent="indigitallThirdParty" target="*-Info.plist">
            <true />
        </config-file>
        <config-file parent="LSApplicationQueriesSchemes" target="*-Info.plist">
            <array>
                <string>fb</string>
            </array>
        </config-file>
        ...
    </platform>
  • Have defined the URL Scheme of the applications that want to be checked in the panel.

3.5.2 Enable service for ANDROID

For can enable the externalApps service in Android is necessary:

  • Put the parameter useExternalApss of the variable options to true in the deviceready event when the library is initialized.

      var options = {
        ...
          useExternalApps: true,
        ...
      };
  • Have defined the applications that want to be checked in the panel

3.6 Get DeviceID

When we talk about DeviceID, we refer to the unique identifier that the indigitall library generates to identify the device and send them push messages. This example indicates how to collect this data in order to work with it.

window.plugins.indigitall.init(options);
window.plugins.indigitall.initStats(function() {
    var deviceID = window.plugins.indigitall.getDeviceId();
    sendToYourBackend(deviceID);
}

3.7 Notifications with images in iOS 10

The options and control of the notifications are improved from iOS 10. PhoneGap has not yet developed any way to include these improvements within the framework, so it is only possible through Xcode natively.

To be able to use these improvements, it is necessary to include a new TARGET in the iOS project called Notification Service Extension.

image

When you add it, you must configure some data such as the Product Name, Bundle Identifier or Language, setting the latter to Swift. Along with the Indigitall library, the files (NotificationService.swift and Info.plist) that this extension should contain are already provided (you will have to overwrite those created by default).

image

Important: to include this extension, you must use Xcode 8.1 or higher and you will have to configure the Deployment Target version of the extension to 10.0 as a minimum, since this extension only runs for versions of iOS 10 or higher.

3.8 App Group configuration for iOS

In this version, several changes have been made to can do a better following of the notification receiving in the device, an so to improve the process of collect data and make the stadistics. These changes affect to NSE configuration and App Capabilities:

  1. Changes in the App Capabilites:

    • Create an App Group for the aplication from Apple console. The format of this group must be like "group.net.MyApp".

    • Enable the "App Group" in the Capabilities of the app and select the group that has been created in the previous step.

    The App Capabilities must be configured like is indicated following:

    Must be enabled the Capabilities Push Notifications and Background Modes. In this last one, must be activated Location updates, Background fetch y Remote notifications.

    image

    The capability App Groups must be enabled too and the group that was created from the Apple console, must be selected. This capability must be configured as is shown in the next image:

    image

  2. Changes in the NSE:

    • Add the App Group, previously created in the Apple console, in the NSE Capabilites del NSE. This group is the same that is added in the App Capabilities.

    • Set the group in the variable groupName in the file NotificationService.m

  3. Set the App Groupof the app in the variable indigitallAppGroup. To do this, you have two options:

    1. In the Phonegap configuration, in the app file config.xml:

      <platform name="ios">
      ...
      <config-file parent="indigitallAppGroup" target="*-Info.plist">
          <string>YOUR_APP_GROUP</string>
      </config-file>
      </platform>

      The configuration must be like is indicated in the point 2.2 of the documentation: iOS Settings

    2. In the Native iOS Project: In the tab Info inside the secction Custom iOS Target Properties of project TARGET, like is shown in the next image:

      image

4. Implementation Updates

4.1 Update to 4.0 from older sdk version

In this verion, to update the SDK will not be necessary add the binarie file manually to native ios project like occured in older versions, only is neccesary:

  1. Download the SDK like is indicated in the point 1.1 of the documentation: Obtaining the Indigitall´s SDK

  2. Delete the plug that was installed with the old version from the directory app/:

    phonegap plugin remove net_indigitall_phonegap
  3. Add the new SDK. For add the plugin must execute the next command in the console from the directory app/:

    • If the SDK was downloaded from indigitall server:

      phonegap plugin add {ruta_hasta_el_directorio_plugin}
    • If the SDK was downloaded from ofical repository:

      phonegap plugin add indigitall
  4. Configure each native project:

5. F.A.Q

  • Q: The notifications do not arrive. What can I do?
  • A: In iOS, look for the "Device Token: {identifier}" message in logs from Xcode. If this message arrives it is because the notification register is being done correctly. If you still do not receive any notifications, revise your "App Token" and check that they are correct. Also check that the certificates sent to the Indigitall team are correct.
    In Android, look for the "Register Service: Device registered" message in the Android Studio logs. If this message arrives it is because the notification register is being done correctly. If you still do not receive any notifications, revise your "App Token" and "Sender ID" and check that they are correct. Some devices like Huawei and Xiaomi have battery economizers that prevent notifications from arriving correctly. If you have such a device, configure it to always receive notifications and, if possible, test with the app in the foreground.

  • Q: To which versions of Android and iOS does Indigitall give support?
  • A: In iOS, the Indigitall library is compiled with deployment Target 6, so, the minimum version that receives support is iOS 6, although it will not receive photos in versions lower than iOS 10 and it will not receive interactives in versions lower than iOS 8.
    In Android, the Indigitall library is compiled with minSdkVersion 16, so, the minimum version of Android that receives support is Jelly Bean (Android 4.1).

  • Q: The image I receive is small, is there any way to fix this?
  • A: In iOS, the notifications with photos in iOS 10 are displayed as a small square at the bottom right on devices prior to iPhone 6. However, for iPhone 6 and later versions, the image can be seen large by giving it the "View" option or with a firm press if the device has 3D Touch.
    In Android, Indigitall’s notifications may include two images, a small square image in the space of the icon and a large panoramic image below the notification body. The large images only appear in the photo-type notifications. Check that, when creating the message in the panel, the image is set to its corresponding field and not to that of the notification icon.

  • Q: In Android I see a square icon in the status bar of the device. Why?
  • A: Since Android 5.0 (Lollipop) the system uses a monochrome icon to represent the application’s notifications in the status bar. If this icon has not been set manually, it will take the application’s icon by default, filling it with white and respecting only its transparencies.
    The Indigitall library allows you to configure the notifications icons with ease by passing them as parameters when it is initialized. See section Initializing the library

  • Q: I do not receive the Geolocalized notifications, how can I fix that?
  • A: In iOS, verify that the geolocation on the device is enabled and that the permissions are granted. Open the app and search, in Xcode, for the logs corresponding to "INDIGITALL_LOCATION", in them you will be able to see how the location changes and if it is significant. We talk about significant changes in the location when the device moves more than 500m (Apple stipulates that this is a significant distance) from the last known position. In Android, verify that the geolocation on the device is enabled and that the permissions are granted. (if it is Android 6.0 or higher). Open the app and search for the logs corresponding to "Location Manager" and "Indigitall Service", in them you will be able to see how the location changes and if it is significant. We talk about significant changes in the location when the device moves more than 100m from the last known position. This service is executed every 20 min by default, being possible to modify the time in the Indigitall panel.

  • Q: My notifications are not positioned first. How do I make this happen?
  • A: In iOS, the notifications are managed by the Operating System and a priority for them cannot be set. In this way, the notification that arrives last will be the one that appears above in the list of notifications.
    In Android, Indigitall’s notifications have the highest priority Android allows, the only notifications that may appear above are those that have the same priority. In these cases, the notification that arrives last will be the one that appears above in the list of notifications if both have the same priority.

  • Q: How do I make development tests without affecting the production users?
  • A: The "App Tokens" of the development application and of the production application are different, this is to avoid the notifications created in development from reaching the users. For this reason, the development tests do not carry any risk. Even so, you can always filter, in the Indigitall panel by DeviceID by creating and uploading a .csv that contains the device identifiers, those to which you want the notification to arrive.

  • Q: How do I make production tests without affecting the users?
  • A: The production tests are very sensitive, since making a mistake here can cause our notification to reach real users. For this reason we advise that when carrying out production tests, make geolocalized deliveries or that they are filtered by DeviceID as explained in the previous case.

6. Contact

In Indigitall, we are happy to help you with any questions or problems that may arise when integrating our solution. To contact us, you can write to us at soporte@indigitall.net We will get back to you as soon as possible.