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.0.2
- fa-sdk-android: 4.0.2
Configuration
IOS
-
Add the following line in the plugin section of
config.xml<gap:plugin name="com.cordova.followapps.plugin" /> -
Run the following command (you need to download the FollowAnalytics Cordova plugin first)
cordova plugin add /path/to/FollowAppsCordovaPlugin -
In your AppDelegate.m, add this import
#import <FollowApps/FAFollowApps.h> -
In your AppDelegate.m, add this line in the method
didFinishLaunchingWithOptions[FAFollowApps configureWithId:API_KEY_STRING debugStateOn:FADEBUG options:launchOptions];
Android
-
Run the following command (you need to download the FollowAnalytic Cordova plugin first)
cordova plugin add /path/to/FollowAppsCordovaPlugin -
Dependency:
FollowAppsCordovaPlugin for Android depends to
google-play-serviceversion8.4.0as framework.So you need to install or update Google Play Services from the
Android Extrassection using the Android SDK manager (runandroid). -
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"> -
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
sudo cordova plugin rm com.cordova.followapps.plugin
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
-
Declare that you want to handle for deeplinking in your Application, after the FollowApps.init(this) line:
FollowApps.setMessageHandler(new CustomPushMessageHandler()); -
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
datais 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.