Android SDK v1.0.0 – Released Aug 26, 2014

Android Getting Started

SDK Overview

The AskingPoint SDK is a drop in library that is driven by Mobile App Analytics and which helps you Improve Ratings, Get Feedback, Support Users and Send Messages. It provides a complete range of services that you control in real-time from the Dashboard. Features include:

Rating Booster – a fully configurable, analytics controlled rating widget that finds your App’s fans and which you control in real-time from your Dashboard.

Add the Required Properties to the Android Manifest(See Android SDK: Add To Project for details).

Call AskingPoint.onStart() from each Activities onStart() method where AskingPoint is needed.
AppKeys are located on an App’s Settings Panel. To see it, select an App in the sidebar and click the Settings
button.

Call AskingPoint.onStop() in each Activity where you called AskingPoint.onStart(). Place the call in the Activities onStop() method.

Keeping Production And Debugging Analytics Separate

To keep Production analytics free of test data and or to be able to do more realistic testing without interrupting production users, add another App to the Dashboard and use that App Key during testing.

Manage which key is used at build time by following the pattern in the next example:

Setting Localized App Name

The AskingPoint SDK sometimes needs to display the App name to End Users on one of the pop-up widgets. For example, the Rating Booster widget.

By default the iOS SDK uses the first value it gets from the Application Bundle, in this order:

The localized CFBundleDisplayName

The CFBundleDisplayName

The localized CFBundleName

The CFBundleName

If you prefer to explicitly set it, call the following function immediately after the call to [ASKPManager startup:] in the Application Delegate:

[ASKPManager setLocalizedAppName:]

To see what name the AskingPoint SDK is currently using, call:

[ASKPManager localizedAppName]

By default the Android SDK uses the value set for label in the AndroidManifest.xml. If you prefer to explicitly set it, call the following function from the Activity that runs first in the App. If more than one Activity can run first, call it from all of them:

Set Reported App Version

AskingPoint uses CFBundleVersionversionName defined in AndroidManifest.xml to report the version of Apps running on devices. This value is displayed on the Dashboard in the Devices and Versions section.

If you wish to explicitly set the reported value to something else, use this function:

NOTE: If you use this function but fail to keep it properly updated, subsequent versions of your App will be reported under an out of date version number. We recommend this feature be used only with automated build systems.

Call this function right after [ASKPManager startup:] in the ApplicationDelegate:

Discontinue Manual Reporting

Set App Store Rating Link

The AskingPoint Android SDK detects the correct Google or Amazon App Store Rating link for production Apps. You don’t need to do anything for that to work correctly. However there are situations where it can be useful to set the link explicitly. For example when:

Your App is in an App store other than Google or Amazon.

You’ve side loaded the App onto a device via some other means.

In these situations AskingPoint can’t detect the correct rating URL and it can be useful to be able to explicitly set it. Use the following methods to explicitly set it:

Note: The value provided to setUserId should be unique for the person owning the device you are setting it on. This value, if set, can be used for integration with Customer Support and Issue Tracking services.

Tags

Tags mark specific locations or events in Apps so that they can be targeted by AskingPoint features from the Dashboard. All AskingPoint features can work with Tags.

Tag usage is not required for features to work, but we strongly recommend using them so as to be able to present AskingPoint widgets at a time and place in App or workflow that does not annoy users.

Some Usage Examples

Example 1: You want to Tag the places in your App where the user finishes a game level or completes an action. These are happy moments and are good times to show Rating Booster.

Example 2: Your App has a feature that can be enhanced by an In-App purchase. If the place where the user starts using that feature is Tagged, you could send an In-App Message offering the item the 1st and 5th times users hit the Tag.

Understanding Tags

Basic Tag concepts:

Tags indicate Where, When and What in App’s work flow.

Whereas, Rules & Conditions indicate Who and When from amongst the user population.

Tags work together with Rules & Conditions. For example, if Rating Booster is targeting a Tag, its Rules & Conditions determine which devices should see it, but only users that hit the specified Tag will actually see it.

You can use more than one Tag with an AskingPoint feature.

And, more than one AskingPoint feature can target the same Tag. AskingPoint ensures users see only one widget at a time.

Tags Are Easy To Use

To Tag places and actions in Apps, put one of the following calls in the code where those actions are controlled:

public static interface OnTagCommandListener {
/**
* Callback to notify when a command request is complete.
*
* @param requestedTag Tag that was requested.
* @param command Command to execute, or null if there was nothing available.
* @return true if the command was processed, false to use the default handler.
*/
boolean onTagCommand(String requestedTag, Command<?> command);
}

Tags are globally unique strings (within an App). Active Tags are displayed on the Dashboard above a features Tag editor, so choose tags that will remind you what they mean when you see them.

Tag Everything Important

We suggest using Tags liberally, and placing them throughout Apps where users enter and leave important places, or initiate and complete important actions. This makes it possible to target a location or activity from the Dashboard anytime and without the need for software updates.

Note: We designed Tags to ensure that heavy usage does not negatively impact App performance. See the SDK Help topic: Tag Performance FAQ.

Tags Without Callback

Tags With A Callback

When it is important to know if something on the Dashboard is or is not firing for a particular Tag, use the next set of functions. These have a Completion Handler on iOS or a Listener on Android and always call your code to let it know if anything is or is not going to fire. Our generic name for these callbacks is Command Handlers.

Command Handlers are always called with arguments indicating if something is or is not firing, and if so which Dashboard feature fired. This gives your code an opportunity to:

Know what is firing.

Do something else when an AskingPoint widget is not firing.

Customize look and feel.

Change behaviors.

For example, using Tags with Command Handlers you could find out if Rating Booster just fired and if not, show an Interstitial Ad.

In Java you implement Command Handlers as listeners which implement OnTagCommandListener Interface.

AskingPoint.requestCommandsWithTag(this, "my_tag", myOnTagListener);

Example – Using A Completion Handler

[ASKPManager requestCommandsWithTag:@"tag" completionHandler:^BOOL(NSString *t, ASKPCommand *c)
{
if(c) {
// Something on the Dashboard is firing for a Command at the time of this request
// Return: YES or NO as per the Command Handler documentation.
}
else {
// Nothing on the Dashboard fired for this Tag at the moment. Ok to do something
// else. Return YES or NO as per the Command Handler documentation.
}
// Anything not caught by one of the above goes to the default handlers
return NO;
}];

Tag Performance

AskingPoint recommends liberal use of Tags. We worked hard to ensure this does not negatively impact App performance. We accomplish this by periodically informing Apps which Tags are actually targeted by something on your Dashboard. This enables the SDK to limit communication with AskingPoint servers to only those Tags being targeted.

FAQ

Does Tag usage negatively impact App performance?No. As discussed above, App’s only communicate with AskingPoint about the Tags currently used on their Dashboard by an AskingPoint feature.

Does Tag usage slow down App launch or portions of of the user interface?No. The SDK communicates with AskingPoint asynchronously, and neither does it block the UI.

How quickly do servers respond to requests for Tags? In most cases the interval between the the request for a Tag and the response is virtually instant. However, your results may vary as round trip communication is subject to the quality and latency of a device’s connection.

Does Tag usage generate a lot of network traffic?No. Our network analysis shows that most Commands sent to Apps are approximately 1k in size. Most of that 1k is SSL overhead and could in future be optimized out.

Custom Events

AskingPoint provides 2 functions for defining Custom Events. Custom Events are useful for tracking the ways
in which Apps and App features are used. Eg, which features are used and/or what options are selected.

1) Event with Name

This is useful for tracking events where simply knowing that something happened is valuable. For example that a
particular feature or button was selected.

[ASKPManager addEventWithName:]

public static void addEvent(String name)

2) Event with Name And Data

This is useful for tracking events and also collecting additional data associated with the event. For
example what path a user took in a game and what weapons they had at the time.

How Timing Durations Are Calculated

The timing functions don’t use any actual timers, they simply log time stamps for the start and stop of the named events. These are sent to our servers where the duration calculations are done.

The rules for determining duration are as follows:

If you start timing something but never fire stop, we don’t count it.

If you start timing something and do fire fire stop, but the App went into the background (iOS) or all Activities stopped (Android), between when start and stop are fired, we divide it into TWO events.

Timed events have no effect on other timed events. We assume concurrency.

Rating Widget Standalone

In addition to being controlled automatically from the Dashboard, Rating Booster rating widget can be called directly from within Apps via the SDK anytime. The main reason you might want to do this is to make it available on a button to allow users to show their appreciation anytime they wish.

canShowRatingPrompt – Returns a boolean indicating if the SDK is ready to show the Rating prompt. There is a very short period of time when Apps first launch where AskingPoint servers update the App with your Custom prompts or our default prompts for a devices language. And also, if you’ve set it to use Store Kit or not.

showRatingPrompt – shows the rating prompt. When the Rating Widget is shown in this way:

Overview – Handling Feedback Notifications

If your App uses Feedback widget during the Rating Booster prompt sequence or the Customer Support widget, there are a few things to be aware of with respect to handling notifications that inform Apps about replies from the dashboard.

Push Notifications

Feedback responses from the Dashboard are sent to Apps via Push messages when Push is enabled on the App’s Push settings tab. Push notifications with responses are seen when the App is in the background. When end-users tap the Push Notification the SDK automatically handles opening the App and presenting the response on the device.

Push notifications will also cause an NSNotification (iOS) or an OnUnreadFeedbackCountChangeListener to be fired within the App more quickly, and so that Apps in the foreground can handle Feedback responses.

NSNotifications/OnUnreadFeedbackCountChangeListener

NSNotifications (iOS) and OnUnreadFeedbackCountChangeListener (Android) are fired while Apps are in the foreground. You can register to get them or the callback to facilitate providing users with visual indicators that responses are available and to display them. Typical uses are:

To badge/unbadge something in the App and indicate a response to the end users feedback is available.

To automatically display your responses to feedback e.g. at App launch or some other time.

For complete documentation see the SDK help topic the Customer Support Widget.

Customer Support Widget Android

Programming is NOT necessary to use Customer Support widget to collect feedback during the Rating Booster prompt sequence. That is controlled the Dashboard with Rating Booster settings.

Starting with SDK v2.0.x Customer Support widget can be quickly and easily added to Apps to support sophisticated two way, chat style conversations. Use it to allow end users to report issues, request features and ask questions which are shown on your Dashboard and to which you can respond.

Note: AskingPoint is happy to work with customers to integrate the Customer Support widget with other Issue tracking services. Contact AskingPoint Support for details.

About Customer Support Widget

Customer support widget takes minimal coding to integrate and includes Notifications and Listeners that can be used to give end users visual indicators that you’ve responded.

showCustomerSupport(Activity parentActivity) – The CustomerSupport Activity collects end user input and displays your responses. It can be attached to a button or called in response to an event you want to collect feedback about.

OnUnreadFeedbackCountChangeListener – When set, the OnUnreadFeedbackCountChangeListener is called when responses are available from the App’s AskingPoint Dashboard or an integrated third party service. They’re triggered most immediately when Push is used to deliver your responses.

getUnreadFeedbackCount() – a convenience method that returns the count of un-read responses.

Examples

Show CustomerSupport Activity

CustomerSupport widget is a standard Android Activity that can be attached to a button or displayed anytime it’s required to offer end-users an opportunity to provide feedback, ask questions or report issues. To show it:

Push Messaging Android

To receive Push messages sent from the AskingPoint Dashboard in your Android Apps(requires SDK v2.0.2 or later)follow the instructions provided by Amazon and Google to get Push credentials. You will need them to configure your Apps.

General Setup

The following setup is required to receive Push messages from either platform (GCM or ADM).

Add the following to the Application section. Replace [YOUR_SENDER_ID] with the Sender Id you received from google, for example “id:999999999999”. The ‘id’ prefix is required to prevent android from interpreting the value as an integer, and truncating it.

Android Advanced

Data Transmission

The AskingPoint SDK sends data when Apps start or come into the foreground, and when they shut down or go into the background. Most Apps are used for short periods of time and sending data at these times is sufficient.

If your App is used in the foreground for long periods of time and you wish to send data more frequently, use the following:

[ASKPManager sendIfNeeded]

AskingPoint.flush()

When called it sends as much cached data as possible. We do not recommend calling it too frequently.

Note: Calling this function has a limited effect on the appearance of analytics on the dashboard. Data received by our servers is cached and processed on various periodic cycles. Some in near real-time with others at end of day.

Payload

Payload makes it possible to deliver blobs of JSON data to Apps from the Dashboard or your servers, in real-time (contact sales about our serverside Payload API).

Payload uses Rules & Tags (like all other AskingPoint features) to enable you to send data to some or all users and at various places and times in App workflow. It makes it possible for Apps to be more flexible in the way they work for segments of the App user population and at Tagged places in Apps. And, you can do this while Apps are deployed in the field, without having to release software update.

Payload Command Handlers

Payload uses Command Handlers like other AskingPoint widgets. See the SDK Help topic: Command Handlers for a full discussion.

Return Values

Payload Command Handlers must return a boolean value of either YES or NO. When YES, the Command must be reported complete after the associated activity finishes.

Base your Command Handler return values on the following considerations:

YES / true: When the Payload Command Handler does UI and/or it is necessary to temporarily prevent other AskingPoint Commands that might pop-up an AskingPoint widget.

NO / false: When the Payload Command Handler is doing something in the background and/or it does not matter if other AskingPoint commands pop-up a widget.

NO / false: When Command Handlers set on Tags are passed nil/null command objects because nothing is firing for the Tag at that time.

When the Command Handler returns YES, use the following function on the Command object to report that
the Payload task is finished:

[command reportComplete];command.complete();

Getting Your JSON Data In The App

The AskingPoint SDK parses JSON data sent from the Dashboard and hands it to Apps in an easy to use form.

On iOS the data is passed as an NSDictionary object containing any of the following data types: NSString, NSArray, NSNumber, NSDictionary.

On Android the data is passed as a JSONObject containing data in valid JSONObject form (See the JSONObject JavaDocs for details).

Command Handlers

Command Handlers provide Apps an opportunity to customize AskingPoint widgets. They are blocks of code you can write and which get called when something on the Dashboard fires a command in the App. For example: Rating Booster or an In-App message is about to show. They can be useful when you want to know if something is about to happen (or not) so that you can do something else or change something.

Setting Command Handlers

Command Handlers are implemented as Block functions on iOS and Listeners on Android and there are two ways to set them:

Command Handler Calling Order

When something on the Dashboard fires and multiple Command Handlers are set in the App, they are called in the following order:

First: those set inline on a Tag that is firing.

Next: the global handler, if one was set on the SDK.

Finally: the default (built-in) handlers if the previous two pass it through or are not set.

In-Line Command Handlers On Tags

The primary benefit of In-Line Command Handlers is:

They always get called and can be used to find out if something did or did not fire for a particular Tag.

They are called at the Tagged location in code where other data and variables which might be needed are available.

These are useful when you would like to do something else if a Dashboard widget does NOT fire at a Tag. For example: If Rating Booster or an In-App message is NOT going to show, let your Ad Provider show an interstitial Ad.

Global Command Handlers

If Global Command Handlers are set they will be called after In-Line Command Handlers. They are called only if a command fires and an In-Line Handler did not already process it.

They are useful when:

You don’t need to know that a command did not fire.

You want to provide a global customization for an AskingPoint widget, e.g. change the appearance of Rating Booster regardless of how triggered.

Default Command Handlers

Default Command handlers are built-in to the SDK by AskingPoint and are invoked automatically when you don’t set any of your own Command Handlers.

Command Handler Return Values

Command Handlers must return a boolean value. The rules for this are, return:

YES / true: When your Command Handler is processing a Command and does not want another Command Handler to process it. This stops processing for the Command at that point.

NO / false: When your Command Handler is not processing a particular Command. This passes the command to the next handler.

NO / false: When Command Handlers set on Tags are passed null command objects because nothing is firing for the Tag at that time.

Reporting Commands Complete

When Command Handlers return YES / true they are telling the AskingPoint default handlers that they are taking responsibility for presentation and button handling and not to show the default widget. In this case your Handler must notify AskingPoint when the user has completed the activity by calling the appropriate function on the Command object:

Not all Commands have buttons that are accessible to your code. When they do, the Command object has a Button property that contains the Buttons you are responsible for handling. When buttons are present, pass the selected button with the call to report completion.

See the SDK Help Topic: Widget Customization for examples of Command Handlers performing the most commonly requested customizations.

Command Handler Object And Type References

For the most complete and current Objects and Type documentation, see the headers in the iOS SDK or the JavaDocs included with the Android version of the SDK.

Examples

These following illustrate a basic Command Handler template:

/*
* In-Line Command Handler on a Tag
*/
[ASKPManager requestCommandsWithTag:@"tag" completionHandler:^BOOL(NSString *t, ASKPCommand *c) {
if(c != nil) {
// Something on the Dashboard fired for this Tag.
// Return YES if you want to stop processing and do something custom.
// Return NO if you want the next or default handler to process it.
}
else {
// Nothing on the Dashboard fired for this Tag.
// Do something else here like show an Interstitial Ad
return NO;
}
// Probably an error, something above did not return properly.
// Return NO and let the default handle it.
return NO;
}];

Widget Customization

Customizing AskingPoint widgets primarily involves writing a simple Command Handler to process Commands for the feature being customized. When it gets called your App has an opportunity to make changes. See the SDK Help Topic: Command Handlers for details.

Using these capabilities it’s possible to customize various aspects of AskingPoint widgets and still continue to control them from the Dashboard.

What can be customized:

Rating Booster:

Appearance – Use AskingPoint translations in your own Rating Widget.

Prompts – Do this from Rating Booster Dashboard settings, rather than in code.

Get User Response – Get notified which button a user selected. See the SDK Help topic: Widget Button Selection.

Messages:

Look & Feel – Use the localized message text sent from your Dashboard in a message widget with your App’s look and feel.

Get User Response – Get notified which button was selected on a Message. See the SDK Help topic: Widget Button Selection.

Reporting Activities Complete

When writing Command Handlers for custom widgets that take responsibility for displaying messages or Rating Prompts, at the end of the operation you must report that a Command completed and also the button selection. See the SDK Help topic: Command Handlers for details.

Also, note the following:

Failure to report Commands complete will cause devices to be prompted again.

Failure to report Commands complete will prevent other types of Dashboard commands from being sent for up to 24 hours.

Custom controllers should NOT process URLs on buttons. E.g. take the user to an App Rating Page. The AskingPoint SDK processes all button URLs after Commands are reported complete.

Examples

The following examples illustrate the most common customization tasks.

Remember to report the Command complete with the button users select. Also, custom widgets should NOT process button URLs, AskingPoint processes those after Commands are reported complete so that we can provide download tracking.

Widget Button Selection

If applications need to know (for their own purposes) how users responded to Rating Booster or an In-App Message, a Global Command Response Handler can be set to get notification of button selection. See the SDK Help topic for Command Handlers if you are unfamiliar with basic Command Handler concepts.

Set the Global Response Handler after the AskingPoint SDK is initialized and before anything else in an Activity is likely to cause something to fire. Safest to do it in the first Activity to get called. The following example outlines the technique for processing data passed to handlers:

Android Other

End User Opt-Out

AskingPoint takes privacy very seriously and while we work hard to protect privacy and believe that our services help improve the End User experience, we understand that some users don’t want to participate under any circumstances. Therefore, we provide 2 mechanisms for End User Opt Out:

1) SDK Functions To Disable/Enable Data Collection And Transmission

The SDK includes 2 functions for turning ON or OFF AskingPoint data collection and transmission from within Apps.

iOS

[ASKPManager setOptedOut:(BOOL)optedOut]

[ASKPManager optedOut]

Android

public static void setOptedOut(boolean optedOut)

public static boolean isOptedOut()

Use setOptedOut to offer End Users an option to disable data collection. The default value is NO/false (opted in) and remains that way until otherwise set.

When data collection has been disabled, it can be re-enabled by calling setOptedOut with a value of NO/false. Use of this function only affects data collection for the App it is used in.

If an End User uses the procedure outlined in 2, AskingPoint servers tell the App to stop collecting data and instruct it to NOT send anything further to our servers. In such cases, calls to setOptedOut from within the App are ignored.

Call optedOut or isOptedOut to learn the current status. These report state regardless of how it got set (via SDK of End User request).

2) Manual End User Opt Out

End Users may contact AskingPoint directly and request a device be Opted-out of AskingPoint services. For details see the information posted here: End User Opt Out. All such requests results in all data for the specified device(s) being removed from AskingPoint servers and the disabling of data collection and transmission in ALL Apps using AskingPoint services.