Principle

The Cordova plugin can be used for Cordova Applications targeting iOS or/and Android application.

FollowApps SDK Versions

The Cordova plugin ships both iOS and Android SDK Version. This version uses:

• fa-sdk-ios: 4.1.0
• fa-sdk-android: 4.1.0

Configuration

IOS

1. Run the following command (you need to download the FollowAnalytics Cordova plugin first)

   cordova plugin add /path/to/fa-sdk-phonegap-plugin
   

2. In your AppDelegate.m, add this import #import <FollowApps/FAFollowApps.h>

3. In your AppDelegate.m, add this line in the method didFinishLaunchingWithOptions

   [FAFollowApps configureWithId:API_KEY_STRING debugStateOn:FADEBUG options:launchOptions];
   

Android

1. Run the following command (you need to download the FollowAnalytic Cordova plugin first)

   cordova plugin add /path/to/fa-sdk-phonegap-plugin
   

2. Dependency:

   FollowAppsCordovaPlugin for Android depends to google-play-service version 8.4.0 as framework.

   So you need to install or update Google Play Services from the Android Extras section using the Android SDK manager (run android).

3. Create an Application Class and initialize the FollowAnalytics SDK in it

   import android.app.Application;
   import com.followapps.android.* ;
   
   public class MainApplication extends Application {
   
       @Override
       public void onCreate() {
           super.onCreate();
           FollowApps.init(this);
           FollowApps.registerGcm()
       }
   }
   

   Don't forget to reference your application class in your AndroidManifest.xml:

   <application ... android:name="MainApplication">
   

4. Inside your application tag add this meta tag with your API KEY*.

   <application>
       .....
     <meta-data android:name="FAID" android:value="API_KEY_STRING" />
       .....
   </application>
   

Initialization

In your device ready, init the plugin FAFollowApps as following:

onDeviceReady: function() {
    ...
    window.FAFollowApps = cordova.require("com/cordova/followapps/plugin");
   ...

};

Usage

Event logging

To log event or error you could do as following:

    <a href="#" onclick="FAFollowApps.logEvent('My event', 'My event details')">Log an event</a>
    <a href="#" onclick="FAFollowApps.logError('My error', '')">Log an error</a>
    <a href="#" onclick="FAFollowApps.logEvent('My event', {'hello': 'Hi', 'How are you': 'good!'})">Log an event with hash</a>

Attributes

User Identifier

If users can sign in somewhere in your app, you can specify their identifier to the SDK. This way, you will be able to relate crashes to specific users, link your users between FollowAnalytics and your CRM, and more.

To do so, use:

    FAFollowApps.setUserID("user_id");

If you want to remove the user identifier (in case of a sign out for instance), please use the method FAFollowApps.unsetUserID();.

User attributes

To set user profile information:

            FAFollowApps.setUserLastName("user_last_name_value");
            FAFollowApps.setUserFirstName("user_first_name_value");
            FAFollowApps.setUserEmail("user_email_value"); 
            FAFollowApps.setUserCity("user_last_city_value"); "// ex:Paris"
            FAFollowApps.setUserBirthDate("2015-10-10");
            FAFollowApps.setUserProfilePicture("user_profile_picture_value");
            FAFollowApps.setUserGender("male");                     // ex: the value must be one of { "male","female", or "other"}
            FAFollowApps.setUserCountry("user_country_value");  // ex: France"
            FAFollowApps.setUserRegion("user_region_value");        // ex: Ile-de-France"

Custom attributes

1. Set a custom attribute

For example, to set the user's job:

 FAFollowApps.setUserAttribute("key_job", "Taxi driver");

2. Delete a custom attribute value

You can delete the value of an attribute by its key. For example, to delete the user's job

FAFollowApps.deleteUserAttribute("key_job");

3. Set of Attributes

You can add or remove an item to or from a set of attributes.

To add an item:

 FAFollowApps.addToUserAttributeSet("key_language","English");
 FAFollowApps.addToUserAttributeSet("key_language","Portuguese");

To remove an item:

 FAFollowApps.removeFromUserAttributeSet("key_language","Portuguese");  //Removes item "Portuguese" from set of languages

To clear a set:

 FAFollowApps.emptyUserAttributeSet("key_language");  //Removes all the items from the set and deletes it.

Push Notification

Register for push

In case you want to register for push through a webview, you need to call registerForPush(), e.g.:

<a href="#" onclick="FAFollowApps.registerForPush()">register for push</a>

For Android you can simply call registerGcm() in your Application Class:

    @Override
    public void onCreate() {
        super.onCreate();
        FollowApps.init(this);
        FollowApps.registerGcm();
        ...

Deeplinking

iOS

Current notification (iOS)

In order to be able to receive the custom parameters sent within a Push Notification or an In App message payload you'll need to implement the followAppsShouldHandleParameters:actionIdentifier:actionTitle:completionHandler: method. Inside your javascript files you'll have to implement a method that will be called from this Objective-C method. If you implement, or instance, a method called doAmazingThings() as follows:

function doAmazingThings(args) {
    console.log(args);
    var currentdate = new Date();
    var datetime = "Last Sync: " + currentdate.getDate() + "/"
    + (currentdate.getMonth()+1)  + "/"
    + currentdate.getFullYear() + " @ "
    + currentdate.getHours() + ":"
    + currentdate.getMinutes() + ":"
    + currentdate.getSeconds();
    document.getElementById('some_element').innerHTML = (datetime);
    console.log('done');
}

You'll be able to call the doAmazingThings() method using the following Objective-C code:

- (void)followAppsShouldHandleParameters:(NSDictionary *)openingParameters
                        actionIdentifier:(NSString *)actionIdentifier
                             actionTitle:(NSString *)actionTitle
                       completionHandler:(void (^)())completionHandler
{
    if (actionIdentifier)
    {
      // here you'll have the identifier for custom push notification actions
    }
    if (completionHandler != nil) {
      // always call the completionHandler, if any
        completionHandler();
    }
    NSData *data = [NSJSONSerialization dataWithJSONObject:openingParameters
                                                   options:NSJSONWritingPrettyPrinted
                                                     error:nil];
    NSString *jsonString = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
    NSString *functionCall = [NSString stringWithFormat:@"doAmazingThings(%@)", jsonString];
    [YOUR_WEBVIEW_INSTANCE stringByEvaluatingJavaScriptFromString:functionCall];
}

Last notification (iOS)

Some applications might not be able to receive the notification custom parameters. Although unlikely, you can call lastPushCampaignParams to get the latest JSON containing the custom parameters passed by the Notification.

Note this is a one shot call as a second call to this method will return an empty JSON.

For iOS,if a push notification is received while the application is on the background it may not be ready to execute the function called from iOS native code. When this happens use the FALastPushMessageContent method to recover the last custom parameters passed by the notification. This function should be used in response to the deviceready event from PhoneGap/Cordova.
To do this you'll need to modify the function inside plugin javascript file. Check the method implementation inside the FAFollowApps.js file in order to see some implementation options.

Android

Default behavior

By default, when the user clicks on a Push notification shown by the FollowAnalytics SDK, an Intent starting a new instance of your main activity is launched. You can retreive any custom parameter in the Java code by adding the following lines in your onCreate method.

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        Bundle extras = getIntent().getExtras();
        if (extras != null) {
            String value1 = extras.getString("a_custom_param_key");
            String value2 = extras.getString("another_key");
            // or retrieve all the pairs
            for (String key : extras.keySet()) {
                Object value = extras.get(key);
                  // …
              }

            // Do what you want with the custom values
          }
    }

Handle deeplinking from Java

If you want more control, you can implement in your Java code the MessageHandler interface, and declare it in your application class, like in the following example.

    public class MyAwesomePushMessageHandler implements MessageHandler {

        @Override
        public void onPushMessageClicked(Context context, Map<String, String> data) {
            String value1 = data.get("a_custom_param_key");
            String value2 = data.get("another_key");

            // Silently do stuff ...
            // .. or start an activity

            Intent intent = new Intent(context, SpecificActivity.class);
            intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
            context.startActivity(intent);
        }

        @Override
        public void onInAppMessageClicked(Context context, String buttonText, Map<String, String> data) {
            // Same as the above method, but from a in-app message !
        }
    }

If you define a custom MessageHandler, you must declare it in your Application, after the FollowApps.init(this) line:

    FollowApps.setMessageHandler(new MyAwesomePushMessageHandler());

Handle deeplinking from javascript

1. Declare that you want to handle for deeplinking in your Application, after the FollowApps.init(this) line:

   FollowApps.setMessageHandler(new CustomPushMessageHandler());
   

2. In your device ready, let we know when the device is ready:

   onDeviceReady: function() {
           ...
           window.FAFollowApps = cordova.require("com/cordova/followapps/plugin");
           FAFollowApps.handleDeeplink();
           FAFollowApps.on("onPushMessageClicked",function(data){
                     console.log(JSON.stringify(data));
   
           });
            FAFollowApps.on("onPushDeeplinkingClicked",function(data){
                     console.log(JSON.stringify(data));
   
                           });
            FAFollowApps.on("onInAppMessageClicked",function(data){
                     console.log(JSON.stringify(data));
   
              });
   
             ....
   },
   

Plugin events:

The plugin provides the following events : onPushMessageClicked , onPushDeeplinkingClicked and onInAppMessageClicked.

PushMessageClicked event:

When the user click on the push, you can retrieve all the added parameter as following:

       FAFollowApps.on("onPushMessageClicked",function(data){
                   //The argument data is an object Json.You can retrieve your value by data.my_key key/value json

    });

onPushDeeplinkingClicked event

When the user click on the push, you can retrieve the url as following:

     FAFollowApps.on("onPushDeeplinkingClicked",function(data){
                 //var my_url = data.url;
                // And do something with it

     });

onInAppMessageClicked event

When the user click on the the in-app button, you can retrieve all the added parameter as following:

     FAFollowApps.on("onInAppMessageClicked",function(data){
                 //The argument data is an object Json.You can retrieve your value by data.my_key key/value json;
                 //the label of button clicked is data.button;

     });

The argument data is the javascript key-value object, you can retrieve the value by the key as following : data["deepurl"]

Rich Campaign pause/resume

You can stop the display of Rich Campaigns in screens where you don't want them to appear. In order to do this call the pauseRichCampaignDisplay.
In order to resume the display of Rich Campaigns use the resumeRichCampaignDisplay method.

URL Scheme to allow full debugging

The FollowAnalytics platform enables you to test campaigns before publishing them. To do so, you need the ID of the device you'll use for the test.

Programmatically, you can just call:

FollowApps.getDeviceId()

If you use a version lower than 4.0.0, to let your application users to retrieve their device ID, edit your AndroidManifest.xml file to add this:

<activity android:name="com.followapps.android.internal.activities.DeviceIdActivity" >
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="followanalytics.com"
            android:path="/deviceId"
            android:scheme="%YOUR_APP_PACKAGE_NAME%" />
    </intent-filter>
</activity>

Once installed, your users can open in a browser (not Chrome ) this URI:

%YOUR_APP_PACKAGE_NAME%://followanalytics.com/deviceId

It will open an activity containing the deviceId.

Note that it does not work with Chrome, because it searches on Google instead of opening the URL. If you have no other browser installed, you can install Firefox.

Migration to 4.1.0

Since the version 4.1.0, the plugin Followanalytics is updated to respect cordova plugin standard. So to call a method, you have to init FAFollowApps instance and call the method.

You can always continue to use the deprecated method.

*All method are renamed and the manner theses methods are called is changed

For example :

FALogEvent('My event', 'My event details')

became

FAFollowApps.logEvent('My event', 'My event details')