App47 Agent Plugin for PhoneGap

App47 Agent Plugin
App473.00
platforms: android,ios
$ cordova plugin add com.app47.plugin

App47 PhoneGap 3.x plugins

iOS Installation

You will first need to download and configure the App47 Agent for iOS. To do this, you'll need to access the native iOS code that PhoneGap will generate for your app. For instance, if you run via the command line:

phonegap local run ios

Next, create a folder in the root of the ios directory that PhoneGap will generate for you called app47. Take the assets from the Agent download and copy them into the app47 directory. For example, your directory should contain:

-rw-r--r--@ 1 aglover  staff      424 Sep 23 14:10 EmbeddedAgentSettings.plist
-rw-r--r--@ 1 aglover  staff    20078 Jul 17 14:02 EmbeddedAgent.h
-rw-r--r--@ 1 aglover  staff  2738596 Jul 17 14:02 libEmbeddedAgent.a
-rw-r--r--@ 1 aglover  staff    55900 Jul 17 14:02 libGMStackTrace.a
-rw-r--r--@ 1 aglover  staff   347132 Jul 17 14:02 libSBJSon.a

You will need to add these files to your project now via Xcode -- you can do this by right clicking on your project in Xcode and selecting the Add Files to... menu item.

Next, in Xcode, find the class named AppDelegate and the following import:

#import "EmbeddedAgent.h"

And add the following lines to the didFinishLaunchingWithOptions method:

[EmbeddedAgent configureAgent];
[EmbeddedAgent InstallExceptionHandlers];

Next, find the EmbeddedAgentSettings.plist file 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 install the PhoneGap 3.x plugin.

Android Installation

You will first need to download and configure the App47 SDK for Android. To do this, you'll need to access the native Android code that PhoneGap will generate for your app. For instance, if you run via the command line:

phonegap local run android

PhoneGap will create a platforms directory, and within it, you'll find an android directory. Drop the latest App47 Android Agent in the libs directory along with the jar dubbed android-support-v4.jar, which is bundled with the App47 Android Agent (this jar adds support for local broadcasting of configuration events).

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 PhoneGap and is usually the name of your App. For instance, if you generated a HellWorld app, your Activity will be named HelloWorld like so:

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

public class HelloWorld extends DroidGap{
    @Override
    public void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
        // Set by <content src="index.html" /> in config.xml
        super.loadUrl(Config.getStartUrl());
        //super.loadUrl("file:///android_asset/www/index.html")
    }
}

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());
    // Set by <content src="index.html" /> in config.xml
    super.loadUrl(Config.getStartUrl());
    //super.loadUrl("file:///android_asset/www/index.html")
}

Note, the call EmbeddedAgent.configureAgent(getApplicationContext()) is asynchronous (but reasonably fast!); thus, we recommend you place this call before PhoneGap 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

You can install, via the command line, the PhoneGap App47 plugin like so:

phonegap local plugin add https://github.com/App47/phonegap-3.x-plugins.git

PhoneGap's new 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 3.x PhoneGap plugins make better use of PhoneGap 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