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:

Configuration

IOS

  1. Add the following line in the plugin section of config.xml

    <gap:plugin name="com.cordova.followapps.plugin" />
  2. Run the following command (you need to download the FollowAnalytics Cordova plugin first)

    cordova plugin add /path/to/FollowAppsCordovaPlugin
  3. In your AppDelegate.m, add this import #import <FollowApps/FAFollowApps.h>

  4. 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/FollowAppsCordovaPlugin
  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*.

    .... .....

Migration from 2.0.0 to 4.0.0

If you already have installed fa-phonegap-plugin version 3.0.0 or older, and you intend to update to 3.4.0, we recommend the following steps:

List all installed plugins

sudo cordova plugin list    //You will see com.cordova.followapps.plugin with version if it's already installed 

Remove fa-phonegap-plugin

sudo cordova plugin rm com.cordova.followapps.plugin

Remove files android-support-v4 and google-play-services from folder libs/

Remove all fa-phonegap-plugin related declaration in manifest.

Add the fa-phonegap-plugin

sudo cordova plugin add /path/to/follow-sdk-plugin

If you have an errors during uninstall step, please update your cordova. We have tested these commands on cordova 6.0.0

Usage

Event logging

To log event or error you could do as following:

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

User ID and attributes

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:

    ```FASetUserId("user_id");
    ```

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

1. Predefined attributes

The SDK allows to set values to both custom and predefined attributes.

For predefined attributes, the SDK has the following setter methods:

 FASetUserLastName("user_last_name_value");
 FASetUserFirstName("user_first_name_value");
 FASetUserEmail("user_email_value"); 
 FASetUserCity("user_last_city_value"); "// ex:Paris"
 FASetUserBirthDate("2015-10-10");
 FASetUserProfilePicture("user_profile_picture_value");
 FASetUserGender("male");                   // ex: the value must be one of { "male","female", or "other"}
 FASetUserCountry("user_country_value");    // ex: France"
 FASetUserRegion("user_region_value");      // ex: Ile-de-France"

They are "predefined" in the sense that they will be attached as default fields on your user profiles.

2. Custom attributes

To ensure the custom attributes you send using the SDK are stored server-side, you must validate them in the profile settings page on the FollowAnalytics product.

Set a custom attribute

For example, to set the user's job:

 FASetUserAttribute("key_job", "Taxi driver");

Delete a custom attribute value

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

FADeleteUserAttribute("key_job");

Set of Attributes

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

To add an item:

 FAAddUserAttribute("key_language","English");
 FAAddUserAttribute("key_language","French");
 FAAddUserAttribute("key_language","Portuguese");

To remove an item:

 FADeleteUserAttribute("key_language","Portuguese");  //Removes item "Portuguese" from set of languages

And to clear a set:

FAEmptyUserAttribute("key_language");  //Removes all the items from the set and deletes it.
<a href="#" onclick="FAEmptyUserAttribute('key_language')">Empty language</a>

Register for Push

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

```<a href="#" onclick="FARegisterForPush()">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();
        ...

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.

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.

Push Notification with custom parameters (deep linking)

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];
}

Get custom parameters from 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.

Android

To receive custom push parameters on Android you have four possibilities:

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() {
        ....
        FAHandlePushNotification();
        ....
        on("notification",function(data){
              //Do something with it
              //For example to go on the page subscription
                if(data["deepurl"] =="subscription"){
                  window.location.href = "subscgription.html#team";
                }
        });
    },

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

    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.