Skip to content

Phonegap 2.9 integration guide

Jump to bottom Edit New page
Andrew Tremblay edited this page Aug 13, 2013 · 1 revision

This page helps to provide an index and walkthrough of each feature we support in our plugin. While we try to supply the same abilities for each version of the SDK, features naturally vary across platforms.

##Before you Begin#

You'll need to make a Project on AppBlade first before implementing any of the features, as valid API keys are required for the SDK to communicate with AppBlade. Your API keys are available under the "Reveal your API Keys" link on the main page of your Project.

##Add AppBlade to your project# Currently our Phonegap plugin supports iOS and Android only. If you have another OS that you would like us to support, email us about it!

Phonegap 2.9 is the one of many Phonegap versions we support. You can go to our version list for other, newer versions of Phonegap.

Due to their inherent differences, each mobile OS comes with their own caveats when plugins are being used. Such caveats are in the sections of each platform.


##iOS Setup##

  1. Copy AppBlade.js into your www/js directory.


2. Copy `AppBladePlugin.h` and `AppBladePlugin.m` into your Plugins folder.

3. Add the AppBlade SDK to your project.
*(These directions are for adding the binary compiled files, adding AppBlade source to a PhoneGap project is currently not supported)* *3a.* Drag the AppBLadeSDK folder with the AppBlade.h and libAppBladeUniversal.a files into your PhoneGap project in Xcode. (Make sure "Copy items" is checked.)
*3b.* Under "Link Binary With Libraries" In your Target's "Build Phases" Click the "+" button and add the Library named "Security.Framework" to your project.
*3c.* Build the Project in Xcode to ensure that everything is running.

4. Ensure "appblade.com" is in Cordova's whitelist.
*4a.* Open your config.xml file and find the access element (the line ``).
*4b.* If the `access` line is already `` Then nothing else needs to be done. ("*" means the whitelist is allowing all sources)
*4c.* If the `access` is not `` Then '' will have to be added.

5. Add AppBlade to your list of plugins
*5a.* Open your config.xml file and find the plugins list element (the line ` ... `).
*5b.* Add `` inside your list of plugins.

6. Make AppBlade.js referenceable.
*There are many ways to do this, as AppBlade.js can be treated jet like any other js file. This is just an example:*
*6a.* In your `index.html` file add `<script type="text/javascript" src="js/AppBlade.js"></script>` after the "cordova-2.9.0.js" script reference and before the "js/index.js" script reference: 
    <script type="text/javascript" src="cordova-2.9.0.js"></script>
    <script type="text/javascript" src="js/AppBlade.js"></script>
    <script type="text/javascript" src="js/index.js"></script>

7. Link your PhoneGap project to AppBlade.com *7a.* To use AppBlade features the app must first exist on AppBlade (click [+ New Project] after signing in). Get your project keys by navigating to your AppBlade project and selecting "Reveal your API Keys".
*7b.* In your `index.js`, underneath the `app.receivedEvent('deviceready');` call the setup method with your SDK keys in the order they appear on the AppBlade site: UUID, token, secret, issued at. The following example sets up the app blade plugin with API keys (actual values not used), sets up the crash reporter, and sets up feedback reporting. 
    onDeviceReady: function() {
      app.receivedEvent('deviceready');
      plugins.appBlade.setupAppBlade('[UUID]','[Token]', '[Secret]', '[Issued at]');
      plugins.appBlade.catchAndReportCrashes();
      plugins.appBlade.allowFeedbackReporting();
    },

See the Example projects included for examples using the other functions of the SDK. ###iOS caveats### There are a few behaviors that you will need to be aware of when using the iOS platform, peruse those caveats on the iOS caveats page.

##Android Setup##

  1. Copy AppBlade.js into your assets/www/js directory.
    1a. In your Package Explorer, expand your project and expand assets > www > js
    1b. Drag AppBlade.js from the AppBlade Plugin Android folder into the js folder in your Package Explorer.
    1c. Make sure "Copy files" is selected before selecting OK.


2. Copy `AppBladePlugin.java` into your project's package directory.
*2a.* In your Package Explorer, expand your project and expand src > [your.package.identifier]
*2b.* Drag `AppBladePlugin.java` from the Android folder into the package in your `src` folder that you would like your plugin to be referenced from. This is usually the package that was created automatically ([your.package.identifier]).
*2c.* Make sure "Copy files" is selected before selecting OK.
*2d.* In your project's copy of `AppBladePlugin.java`, change the package name from 'com.appblade.phonegappluginexample' to your package identifier.

3. Add the AppBlade SDK to your project.
*(These directions are for adding the app blade framework jar, adding AppBlade source to a PhoneGap project is currently not supported)*
*3a.* Open your `libs` folder under your project in the Package Explorer.
*3b.* Drag the included `appblade framework.jar` and `httpmime-4.1.2.jar` into the libs folder.
*3c.* Make sure "Copy files" is selected before selecting OK.

4. Ensure AppBlade.com is in Cordova's whitelist.
*4a.* Open your config.xml file and find the access element (the line ``).
*4b.* If the `access` line is already `` Then nothing else needs to be done. ("*" means the whitelist is allowing all sources)
*4c.* If the `access` is not `` Then `` will have to be added.

5. Add AppBlade to your list of plugins
*5a.* On Your Package Explorer, open your project's `config.xml` file in `res` > `xml` > `config.xml`
*5b.* Open the file with the text editor (right-click > `Open With...` > `Text Editor`, if necessary) and locate the plugins list element (the line ` ... `).
*5c.* Add `` inside your list of plugins. `[your.package.identifier]` is where `AppBladePlugin.java` is stored in your project's packages.

6. Make AppBlade.js referenceable.
*There are many ways to do this, as AppBlade.js can be treated jet like any other js file. This is just an example:*
*6a.* In your `index.html` file add `<script type="text/javascript" src="js/AppBlade.js"></script>` after the "cordova-2.9.0.js" script reference and before the "js/index.js" script reference: 
    <script type="text/javascript" src="cordova-2.9.0.js"></script>
    <script type="text/javascript" src="js/AppBlade.js"></script>
    <script type="text/javascript" src="js/index.js"></script>

7. Link your PhoneGap project to AppBlade.com *7a.* To use AppBlade features the app must first exist on AppBlade (click [+ New Project] after signing in). Get your project keys by navigating to your AppBlade project and selecting "Reveal your API Keys".
*7b.* In your `index.js`, underneath the `app.receivedEvent('deviceready');` call the setup method with your SDK keys in the order they appear on the AppBlade site: UUID, token, secret, issued at. The following example sets up the app blade plugin with API keys (actual values not used), sets up the crash reporter, and sets up feedback reporting. 
    onDeviceReady: function() {
      app.receivedEvent('deviceready');
      plugins.appBlade.setupAppBlade('[UUID]','[Token]', '[Secret]', '[Issued at]');
      plugins.appBlade.catchAndReportCrashes();
      plugins.appBlade.allowFeedbackReporting();
    },

See the Example project included for examples using the other functions of the SDK.

###Android caveats### There are a few behaviors that you will need to be aware of when using the Android platform, read up on the details on the Android caveats page.


##Feature-by-Feature implementation## ###Crash Reporting### Enabling crash reporting allows your app to send stack traces to AppBlade for desymbolication, analysis, and third party support tools. Setting up AppBlade Crash Reporting takes only one line of code, after your setupAppBlade call `plugins.appBlade.catchAndReportCrashes();` in onDeviceReady 
    onDeviceReady: function() {
      app.receivedEvent('deviceready');
      plugins.appBlade.setupAppBlade('[UUID]','[Token]', '[Secret]', '[Issued at]'); //always required
      plugins.appBlade.catchAndReportCrashes();
      //the rest of your features
    },

Crash Reporting should work on simulator, but devices connected to a debugger might not generate a crash report log, so they won't be generated.

###Feedback Reporting### Enabling feedback reporting allows your app to send a feedback message (and optional screenshot) to AppBlade for review by a project administrator, developer, or designer, you also can integrate it with third party support tools like github.

Setting up AppBlade Feedback Reporting takes — at most — one line of code and comes with a few optional parameters, after your setupAppBlade call plugins.appBlade.allowFeedbackReporting(); in onDeviceReady

    onDeviceReady: function() {
      app.receivedEvent('deviceready');
      plugins.appBlade.setupAppBlade('[UUID]','[Token]', '[Secret]', '[Issued at]'); //always required
      plugins.appBlade.allowFeedbackReporting();
      //the rest of your features
    },

If you are only building a phonegap project for Android, this setup call is optional. And there you go, the app is set up to send feedback. To send feedback to AppBlade, you'll need to prompt our native dialog window. You can trigger the window by double-tapping three fingers on the screen. Alternatively, you can call trigger the dialog window yourself from inside a UI function.

plugins.appBlade.showFeedbackDialog();

Passing an optional "noScreenshot" variable will disable the screengrab.

plugins.appBlade.showFeedbackDialog("noScreenshot");

Feedback Reporting should work on most simulators. If you see lag on the device, it might be because the screen is too big for the processor to grab and store the screen image in a timely manner.

###Session Tracking###

Session tracking allows you to see when users open and close your app on their devices. It doesn't require a setup call. Start a session by calling

plugins.appBlade.startSession();

Where you want the app to be considered "begun", (usually in onDeviceReady)

And end a session by calling

plugins.appBlade.endSession();

There isn't a set place to put this endSession, since app state can be tricky to track on some devices. The best place to usually put it would be on the pause event that phonegap provides.

document.addEventListener("pause", onPause, false);

function onPause() {
    plugins.appBlade.endSession();
}

###Update Checking###

Update Checking checks with AppBlade to see if a newer version of your project is available. If one is available, the SDK will attempt to download and install your newer version to your device. This keeps your testers always up to date with the latest build you've release. No need for them to sign into AppBlade either, the updates occur anonymously.

There's no additional setup required to use Automatic Updates, just call plugins.appBlade.checkForUpdates() from anywhere in your app.

    onDeviceReady: function() {
      app.receivedEvent('deviceready');
      plugins.appBlade.setupAppBlade('[UUID]','[Token]', '[Secret]', '[Issued at]'); //always required
      //the rest of your features
      plugins.appBlade.checkForUpdates();
    },

###Authentication Checking & KillSwitch ###

AppBlade supports App Authentication Checking and a "Kill Switch" feature. When enabled, only users who have access to your AppBlade project can open and use the app. Unauthorized use will close the app immediately. Users added and then removed from your project will become unauthorized and have their app use revoked. This guarantees that only the AppBlade users you specify can use your app.

To check users for their authentication, call 'plugins.appBlade.checkAuthentication()' after your setup steps.

    onDeviceReady: function() {
      app.receivedEvent('deviceready');
      plugins.appBlade.setupAppBlade('[UUID]','[Token]', '[Secret]', '[Issued at]'); //always required
      //the rest of your features
      plugins.appBlade.checkAuthentication();
    },

###Custom Parameters###

Custom parameters are special variables that AppBlade stores and sends along with other API calls to help you track and organize your data. Feedback Reporting, Crash Reporting, and Session Tracking all take advantage of custom parameters.

Custom parameters require no setup and can be called from whatever function you'd like. You should treat them like hashes or dictionaries.

Set a parameter named [your_key] by calling plugins.appBlade.setCustomParameter('[your_key]', '[your_value]')

Clear a parameter named [your_key] by calling plugins.appBlade.setCustomParameter('[your_key]', null)

Clear all stored parameters by calling plugins.appBlade.clearCustomParameters() .

Add a custom footer
Add a custom sidebar
Clone this wiki locally