App47 plugin for Cordova (PhoneGap) version 6.x

##iOS Installation

Create your project using the Cordova CLI:

cordova create AppName

Next add in the iOS platform:

cd AppName
cordova platform add ios

Finally add in the App47 plugin

cordova plugin add <path to App47 Plugin>

Open the project in Xcode and on the Project/General tab add the EmbeddedAgent.framework to the Embedded Binaries since this is a custom framework that will need to be bundled with the app. This is currently an issue with Cordova that the embed="true" on a framework does not embed the framework. Next, in Xcode, find the class named AppDelegate and the following import:

#import <EmbeddedAgent/EmbeddedAgent.h>

And add the following lines to the didFinishLaunchingWithOptions method:

[EmbeddedAgent configureAgent];
[EmbeddedAgent InstallExceptionHandlers];

Next, find the EmbeddedAgentSettings.plist file in the Resources folder and add your app's id, which you can find in your App47 account dashboard.

That's it for iOS -- please see the below section entitled "Using the App47 Agent" for how to use the Cordova 6.x plugin.

##Android Installation

Create your project using the Cordova CLI:

cordova create AppName

Next add in the Android platform:

cd AppName
cordova platform add android

Finally add in the App47 plugin

cordova plugin add <path to App47 Plugin>

Configuring the Android Agent

Next, you'll want to configure your Android app like it was a native app; that is, you'll want to add Embedded Agent services to your AndroidManifest.xml. For instance, you'll need to add the following services:

<service android:enabled="true" android:name="com.app47.embeddedagent.AgentConfigService"/>
<service android:enabled="true" android:name="com.app47.embeddedagent.AgentSessionService"/>
<service android:enabled="true" android:name="com.app47.embeddedagent.AgentEventService"/>

And the following permission if you wish to include location information to your agent data.:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

Next, you'll need to open up your App's main Activity -- this is an Activity that was generated by Cordova and is usually the name of your App. For instance, if you generated a HellWorld app, your Activity will be named HelloWorld like so:

package io.cordova.hellocordova;

import android.os.Bundle;
import org.apache.cordova.*;

public class MainActivity extends CordovaActivity
{
    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);

        // enable Cordova apps to be started in the background
        Bundle extras = getIntent().getExtras();
        if (extras != null && extras.getBoolean("cdvStartInBackground", false)) {
            moveTaskToBack(true);
        }

        // Set by <content src="index.html" /> in config.xml
        loadUrl(launchUrl);
    }
}

You will need to overload two methods: onResume and onPause in that Activity class like so:

protected void onResume(){
	super.onResume();
	EmbeddedAgent.onResume(getApplicationContext());
}

protected void onPause(){
	super.onPause();
	EmbeddedAgent.onPause(getApplicationContext());
}

You'll also need to add the following import to that same class:

import com.app47.embeddedagent.EmbeddedAgent;

Finally, you will need to update the onCreate method by adding a call to initialize the EmbeddedAgent like so:

public void onCreate(Bundle savedInstanceState)
{
    super.onCreate(savedInstanceState);
        
    EmbeddedAgent.configureAgent(getApplicationContext());
    
    // enable Cordova apps to be started in the background
    Bundle extras = getIntent().getExtras(); 
    if (extras != null && extras.getBoolean("cdvStartInBackground", false)) {
        moveTaskToBack(true);
    }
    
    // Set by <content src="index.html" /> in config.xml
    loadUrl(launchUrl);
}

Note, the call EmbeddedAgent.configureAgent(getApplicationContext()) is asynchronous (but reasonably fast!); thus, we recommend you place this call before Cordova loads your web app (via the loadUrl call).

There are 2 ways to configure the EmbeddedAgent -- you can either create an XML resource file in your Android's res/values directory that looks something like this:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="EmbeddedAgent_applicationID"><your app id goes here></string>
  <string name="EmbeddedAgent_configurationUpdateFrequency">0.5</string>
  <string name="EmbeddedAgent_delayDataUploadInterval">10</string>
  <string name="EmbeddedAgent_sendActualDeviceIdentifier">false</string>
</resources>

Or you can programatically configure the agent via the configureAgentWithAppID method (note, this is done in the onCreate method.

Using the App47 Agent

Cordova's plugin mechanism makes things a lot easier because the name app47 will essentially be injected into your app's JS files. Thus, you can access corresponding methods like so:

app47.genericEvent("awesome event");

Where the code above invokes a generic event named "awesome event". Note, the App47 6.x Cordova plugins make better use of Cordova JavaScript callbacks like so:

app47.timedEvent("button pressed", function(timedEventId){
  //timedEventId is the ID from starting a timed event
  //code to press a button, etc
  //App47 PG plugin will automatically stop the timed event
});

Note in the code above, there is no need to start nor stop a timed event -- the code in the callback (which is passed in the event's id) will be invoked and after a successful invocation, the timed event will be stopped. You can optionally pass in a 2nd function that'll be invoked upon some error.

License

The MIT License

Copyright (c) 2013 App47, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE