Apache Cordova Fovea Context Engine Plugin

This is the plugin for Fovea Context Engine in Apache Cordova/PhoneGap!

The Fovea Context engine adds intelligence to any mobile app! It enables the host mobile app to mine the contextual data from his/her mobile phone, helping to gain meaningful insights, patterns and behaviour about the app user.

App owners can leverage this engine to derive awesome use cases for his business at various stages. In its current version, Fovea engine aims at delivering the following services:

• App Virality (referral) as service, which aids app recommendation driven by user to his close circle. When triggered, fovea provides user’s most influential people, for whom app-links are sent via SMS upon his approval.
• Informative dashboards revealing insights about App’s user base - User demography by location, App usage patterns
• Product discovery, driven by app personalisation and recommendation for each user.

All of the above features heavily relies upon the data /insights mined from the Fovea mobile context engine, which involves various context mining operations. Developers have flexibility to subscribe to only select services, for which they are comfortable seeking relevant permissions from users during the app installation.

The Fovea context engine relies on following mining operation for the available services. We recommend developers to enable all these services to benefit from Fovea to the maximum extent. However, engine is configurable to the selected services as specified during the SDK initialisation method.

• App Virality ( Call logs and optionally, Facebook)
• App Usage Dashboards (App usage)
• User demography dashboards (Location intelligence)
• Product discovery ( Configurable with only few services - Call logs, Browser history, Apps usage, Facebook context )

Install the plugin (cordova)

cordova plugin add fovea_context_engine

Fovea Requirements and Set-Up

To use this SDK, you will need to make sure you've registered your app with Fovea portal and have collected your developer keys - App key and Client keys.

Fovea integration setup

1. Update the plugin.xml for required permissions as needed

Based on the services selected, special permissions may need to be added to allow user to authorize access to the target data. These tags need to be added as children to the manifest node in the manifest file. Listed below are the permissions required categorized by the services they support. To ensure proper functioning of library, necessary permissions associated to services requested must be added to the Manifest.

Excerpt of the plugin.xml:

<!-- App Virality -->
<uses-feature android:name="android.hardware.telephony" android:required="false" />
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.SEND_SMS" />
<uses-permission android:name="android.permission.READ_CALL_LOG" />

<!-- Apps usage dashboard —>
<uses-permission android:name="android.permission.GET_TASKS" />
<uses-permission android:name="android.permission.PACKAGE_USAGE_STATS" tools:ignore="ProtectedPermissions" />
<!--Also add ' xmlns:tools="http://schemas.android.com/tools" ' to the root manifest tag-->

<!-- User demography dashboard-->
<uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<!-- Product discovery—>
<uses-permission android:name="com.android.browser.permission.READ_HISTORY_BOOKMARKS"/>
<uses-permission android:name="android.permission.READ_CALL_LOG" />
<uses-permission android:name="android.permission.GET_TASKS" />
<uses-permission android:name="android.permission.PACKAGE_USAGE_STATS" tools:ignore="ProtectedPermissions" />
<!--Also add ' xmlns:tools="http://schemas.android.com/tools" ' to the root manifest tag-->

Fovea interface integration

2. Initialize the Fovea Context Engine SDK, Set business user profile details and Facebook access token for the logged in user.

Initialize SDK

fovea.initialize(String appKey, String clientKey, Array strings of mining services, Function success, Function failure)

Sample Usage:

initializeFovea: function() 
{
    //Pass the APP Key
    var appkey = "***** APP KEY goes here *****";

    var clientKey = "***** Client KEY goes here *****";

    //Pass in the interested services
    var services = ["APP_VIRALITY","APP_USAGE_DASHBOARD","APP_USERLOCATION_DASHBOARD","DISCOVERY","FB"];
    var success = function() 
    { 
        alert("Success");    
        app.setCustomerProfile();
    };
    var error = function(message) 
    {
        alert("Oops! " + message); 
    };
    fovea.initialize(appkey, services, success, error);
}

Result: Success callback notifies the successful initialization, where as exception message is passed to failure callback in case of failure.

Note : 1.This API must be invoked when there is network connectivity. 2.One must make sure the necessary permissions for each selected context mining services is enabled on Config.xml and hence app manifest.

Set Customer Profile

fovea.setCustomerProfile(String userName, String uniqueUserID, String emailID, String phoneNo, int gender, String dateOfBirth, Function success, Function failure)

Sample Usage:

setUserProfile: function()
{
    //Mandatory, Unique user ID to identify the loggen in user
    var uniqueUserID = "35671";
    var userName = "John";
    var emailId = "[email protected]";
    var phoneNo = "324-443-4444";

    //Gender constant {0- Undisclosed, 1-Male, 2-Female, 3-Other}
    var gender = 1;

    var dob = "dd/mm/yyyy";
    var successCallback = function() 
    { 
        app.setFacebookToken(); 
    };

    var errorCallback = function(message) { alert("Oops! " + message); };

    fovea.setUserProfile(userName,uniqueUserID,emailId,phoneNo, gender, dob, successCallback, errorCallback);
}

Result: Success callback notifies the successful initialization, where as exception message is passed to failure callback in case of failure.

Note: This method is ideally be called on each new user logging in to the app.

Set Facebook access token

fovea.setFacebookToken(String token,Function success, Function failure)

Sample Usage:

setFacebookToken: function() 
{
    var token = "******** FB access token goes here *******";
    var success = function() { alert("FB Success"); };
    var error = function(message) { alert("Oops! " + message); };
    fovea.setFBToken(token, success, error);
}

Result: Success callback notifies the successful initialization, where as exception message is passed to failure callback in case of failure.

Note: This method is ideally be called on each new user logging in to the app as well as Facebook login session is refreshed.

Get Recommended Invitees for App referral

fovea.getAppInvitees(Function success, Function failure)

Sample Usage:

getAppInvitees: function() 
{
    console.log('Received Get App getAppInvitees event');
    var success = function(result) 
    { 
        var jsonObj = eval('(' + result + ')');
        console.log('json output :' + jsonObj);
        if (typeof jsonObj !== 'undefined' && jsonObj.length > 0) 
        {
            //Present the resulted recommendations to user to get his consensus to proceed with sending out app invitations via SMS
        }   
    };
    var error = function(message) {
        alert("Oopsie! " + message); 
    };
    fovea.getAppInvitees(success, error);
}

Result: Success callback notifies the successful initialization, where as exception message is passed to failure callback in case of failure.

Note:

1. This API would be only applicable if App virality service is activated during the Fovea SDK initialization.
2. The recommendations would be available only after 5 minutes after the app is launched (for the first time).

Proceed with sending out the App invitations

fovea.proceedWithAppInvites(JSONArray approvedInvitees, JSONArray declinedInvitees, String invitationMessage, Function success, Function failure)

Sample Usage:

proceedWithAppInvites: function(approvedInvitees, declinedInvitees) 
{
    console.log('Received proceedWithAppInvites event');
    var success = function() { alert("success"); };
    var error = function(message) { alert("Oopsie! " + message); };
    var selectedInvites = approvedInvitees;
    var declinedInvites = declinedInvitees;
    var msg = "You'll love this cool app, powered by Fovea! Checkout https://example.com/getapp";
    fovea.proceedWithAppInvites(selectedInvites,declinedInvites,msg,success, error);
}

Result: This method proceeds with sending out the app invitations via SMS. Success callback notifies the successful initialization, where as exception message is passed to failure callback in case of failure.