Skip to content

Feature Implementation Guide

Jump to bottom
jamesdaniels edited this page Nov 21, 2014 · 29 revisions

For earlier versions of our SDK, check out our Old Feature Implementation Guide

This page helps to provide an index and walkthrough of each feature we support in our SDKs. Organized by platform.

While we try to supply the same abilities for each version of the SDK, features naturally vary across platforms.

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.

###Index#

##iOS# iOS is supported to work in both native Objective-C and Objective-C++. If you use another method to develop in iOS, like PhoneGap, our plugin page might be more your speed.

Registration is required before calling other features in iOS, since we need a Project ID and the other API information to communicate with AppBlade. Calling any other AppBlade function before registering will throw an AppBladeException telling you which field was left empty or invalid. Example of such an exception:

*** Terminating app due to uncaught exception 'AppBladeException', reason: 'AppBlade AppBladeKeys not set.
 Configure the shared AppBlade manager from within your application delegate or AppBlade plist file.'

That means you'll need to Register and Setup your project with proper project keys from AppBlade, which might mean getting the new SDK installation steps from AppBlade if you're updating from an old SDK.

These sections assume you've already followed through with adding the libAppBladeUniversal.a Library or the source to your project and you've added AppBlade.h to your imports. Directions for doing that can be found here.

###Registration & Setup# Registration should be called before any other AppBlade function, so naturally you'd want it declared as early in the process as possible; in the `-application:didFinishLaunchingWithOptions:` function of your `AppDelegate` class. 
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    AppBlade *blade = [AppBlade sharedManager];
    [blade registerWithAppBladePlist];
...

}

Your AppBlade sharedManager instance then registers itself with the AppBladeKeys.plist which you added via your AppBlade Project page.

###Authorization and Kill Switch# If you want to authorize the app to specific users or testers during development, call `[[AppBlade sharedManager] checkApproval];` whenever you want to ensure the build is allowed to be run. This usually occurs within `- (void)applicationDidBecomeActive:(UIApplication *)application`.

Since third-party authentication is prohibited by Apple, and updates are supposed to be handled through the AppStore, this feature will be bypassed automatically if the ipa is signed by Apple. Builds submitted to the AppStore will ignore calls to this method.

###Update notifications# Update notifications check with AppBlade and notify the user if a newer version of the app is available. Unlike the updating that occurs during the `[[AppBlade sharedManager] checkApproval];` call, *anonymous updating* can be done outside the authorization process. Due to this, users will only be notified of new versions when they are running a build downloaded from AppBlade and that version is on the GeneralRelease track.

Updating can be called by putting [[AppBlade sharedManager] checkForUpdates]; anywhere in your code, preferably in -application:didFinishLaunchingWithOptions: or -applicationDidBecomeActive:.

- (void)applicationDidBecomeActive:(UIApplication *)application
{
    // Check the app blade update status of this application.
    [[AppBlade sharedManager] checkForUpdates];

    //Do additional things on resume.
}

Since third-party updating is prohibited by Apple, this feature will be bypassed automatically if the ipa is signed by Apple. Builds submitted to the AppStore will ignore calls to this method.

###Crash Reporting# To register our uncaught crash reporter, call `[[AppBlade sharedManager] catchAndReportCrashes];` after the AppBlade API keys are defined. ###Feedback Reporting# Feedback reporting comes with a dialog prompted by a three-finger double-tap. `[[AppBlade sharedManager] allowFeedbackReporting];` Enables it.

To enable feedback reporting without the three-finger double-tap prompt, use [[AppBlade sharedManager] setupCustomFeedbackReporting]; and then prompt the feedback window somewhere in your app with [[AppBlade sharedManager] showFeedbackDialogue]. We automatically force one feedback window at a time.

###Session Counting# User statistics are great for tracking when users open and background your application. Call `[[AppBlade sharedManager] logSessionStart];` under `- (void)applicationDidBecomeActive:(UIApplication *)application` in your AppDelegate.

Add a call to [[AppBlade sharedManager] logSessionEnd]; under both - (void)applicationWillTerminate:(UIApplication *)application and - (void)applicationWillResignActive:(UIApplication *)application in your AppDelegate. If your app is also meant to background for a specific reason, (such as opening a webpage in Safari), you might need to add conditionals to ensure that you're ending sessions appropriately based on how you want your app to work.

###Custom Parameters# Custom parameters are treated as an `NSDictionary` whose variables can be set from anywhere (after your appblade code is registered). Set them with the call `-(void)setCustomParams:(NSDictionary *)newFieldValues` and get the current set params with `-(NSDictionary *)getCustomParams`. To set a single key/value pair, use `-(void)setCustomParam:(id)object forKey:(NSString*)key`, and to clear all params, call `-(void)clearAllCustomParams`.
Custom parameters are considered unique to every crash or feedback, so you'll have to reenter data that you want to be persistent.
Currently there isn't a limit to how many parameters you can send, or what they can contain, but please don't go too crazy with them. Also, please respect the privacy of the user and only track application details.

<br> <br>

##Android# Our Android SDK is supported in a basic Eclipse environment with the Android Debug Tools installed. The easiest way to do this (if you haven't already) is through the Google [ADT Eclipse plugin](http://developer.android.com/tools/sdk/eclipse-adt.html).

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.

These sections assume you have already either imported the AppBlade Android source or imported our compiled library into your workspace. Directions for doing that can be found here.

###Registration & Setup# Registration should be called before any other AppBlade function, so naturally you'd want it declared as early in the process as possible. The best way to ensure this is to make a custom Application class (if you don't already have one) and put your registration inside the `onCreate()` method.

To register a custom Application class for your Android app, you will need to refer to it by name in the application element of your project's manifest. For example:

<application android:name=".YourApplication">
    <activity
        android:name="com.yourpackage.YourMainActivity"
        android:label="@string/app_name" >
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>
</application>

Then, register your application details in your Application class' onCreate method:

import com.appblade.framework.AppBlade;

import android.app.Application;

public class YourApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    String token = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
    String secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
    String uuid = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
    String issuance = "9999999999";
    
    AppBlade.register(this, token, secret, uuid, issuance);
  }
}

ALSO: Be sure that your application has permission to access the internet to communicate with our server (and store failed requests when it can't) by adding the following permissions to the manifest:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

In the end, your AppBlade manifest should look something like this.

	<?xml version="1.0" encoding="utf-8"?>
	<manifest xmlns:android="http://schemas.android.com/apk/res/android"
	    package="com.example.yourpackagename"
	    android:versionCode="1"
	    android:versionName="1.0" >
	    
	    <uses-permission android:name="android.permission.INTERNET"/>
	    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
	    
	    <uses-sdk
	        android:minSdkVersion="8"
	        android:targetSdkVersion="17" />
	
	    <application android:name=".YourApplication"
	        android:allowBackup="true"
	        android:icon="@drawable/ic_launcher"
	        android:label="@string/app_name"
	        android:theme="@style/AppTheme" >
	        <activity
	            android:name="com.example.yourpackagename.YourMainActivity"
	            android:label="@string/app_name" >
	            <intent-filter>
	                <action android:name="android.intent.action.MAIN" />
	                <category android:name="android.intent.category.LAUNCHER" />
	            </intent-filter>
	        </activity>
	    </application>
	
	</manifest>
###Authorization and Kill Switch# To enable the AppBlade killswitch and allow AppBlade to enforce user authorization in your app, call AppBlade.authorize statically from your main activity's onResume method. 
    public class MainActivity extends Activity {
        public void onResume() {
            super.onResume();
            AppBlade.authorize(this);
        }
    }


You'll need to declare our RemoteAuthorizeActivity among the other activities in your manifest as well, or roll your own Activity. This allows users to sign in through our included webview.

		<activity android:name="com.appblade.framework.authenticate.RemoteAuthorizeActivity" />
###Update notifications# Update notifications check with AppBlade and notify the user if a newer version of the app is available. The user can be prompted to download the app and the installation of the new version is handled internally without pushing out to a web browser (Though the download manager is utilized if it is available). The `WRITE_EXTERNAL_STORAGE` permission is required to download the update, since the new apk cannot be stored locally. The apk is deleted after a successful installation and first launch. Inside the `onResume` of your main activity, call `AppBlade.checkForUpdates(YourMainActivity.this)` Since Android updates are currently anonymous-only, users will only be notified of new versions when they are running a build downloaded from AppBlade and only when that version is on the GeneralRelease track. ###Crash Reporting# To enable crash logging globally for your app for all uncaught exceptions, call `AppBlade.registerExceptionHandler();` after your `AppBlade.register(this, token, secret, uuid, issuance);` call. This will grab all uncaught exceptions and attempt to notify AppBlade of them on the next resume of the app. (If you already registered an UncauahtExceptionHandler, our exception handler will store a reference to it and pass the exception down to it). You can also notify AppBlade for a specific exception within your code that you are catching yourself. With in the `try/catch` block of the exception, Add `AppBlade.notify(ex);` of the Exception `ex` that you're catching. See our example project for a working example. ###Feedback Reporting# Unlike iOS, Android does not require any setup call to enable feedback reporting. To prompt a basic feedback reporting dialog, just call the following from within your Activity. 
    AppBlade.doFeedback(YourActivity.this);


To also include a screenshot to send to AppBlade with your feedback, include an Activity, a View, or a Bitmap or with one of the following functions:

    AppBlade.doFeedbackWithScreenshot(Context context, Activity activity);
    AppBlade.doFeedbackWithScreenshot(Context context, View view);
    AppBlade.doFeedbackWithScreenshot(Context context, Bitmap bitmap);

A precoded dialog will then prompt the user to fill out a message and an option to send the included screenshot.

###Session Counting# To use Session counting, call `AppBlade.startSession()` and `AppBlade.endSession()` in the `onResume()` and `onPause()` functions of your main `Activity`, respectively. *(Or wherever you think is appropriate. The lifespan of Android apps are notoriously difficult to track, and will vary depending on your implementation.)* ###Custom Parameters# Custom Parameters can be included along with Feedback, Crash reports, and Sessions. Call `AppBlade.setCustomParameter(Context, String, Object)` to set or clear a value to send or call `AppBlade.clearCustomParameters(Context)` to clear all stored variables.
*Unlike the iOS implementation of AppBlade, the Android SDK uses persistent custom parameters, so you'll have to manually clear them if you don't want them sent.*
Clone this wiki locally