AppBucks SDK v2.0 Documentation

Installation Prior to reading this document, please be sure to obtain your Developer API Key and App ID from the

AppBucks Developer Portal, as you will need these to initialize the SDK.

QUICK START Open the AppBucksSampleApp project (included in the zip) in Eclipse and use it as a starting app.

Be sure to set your App ID and Api Key.

Step 1 – Add the JAR to your project (ADT version >= 18)

In Eclipse, this is achieved through the following steps (if you are using a version of the Android

Developer Tools below version 18, proceed to step 1a instead):

1. Make sure your project has a directory called “libs.” If not, create one.

2. Right-click the “libs” directory and choose Import→General→File System, then click “Browse”

and browse to the directory where you saved the MobileSDK.jar file and click OK.

3. Click the directory name in the left pane (do not check the checkbox), and then check the

checkbox next to MobileSDK.jar in the right pane.

4. Click “Finish.” You should now see MobileSDK.jar under both the “libs” and the “Android

Dependencies” directories in your project.

5. [ADT version 22 or later only]. Right-click your project and select “Properties” from the drop-

down. In the Properties dialog box, select “Java Build Path” on the left side, and then select the

“Order and Export” tab. Verify that “Android Private Libraries” is checked.

Step 1a – Add the JAR to your project (ADT version < 18)

1. Copy the MobileSDK.jar file to your project’s root directory

2. Right-click your project in the Package Explorer tab and choose “Properties”

3. Select “Java Build Path” from the left panel

4. Select the “Libraries” tab

5. Click the “Add JARs…” button

6. Select the MobileSDK.jar file that you copied to your project’s root directory and click OK

7. Select the “Order and Export” tab and make sure the MobileSDK.jar file is checked

Step 2 – Modify your AndroidManifest.xml file

Place the following XML just before the closing </Application> tag in your AndroidManifest.xml file:

<!-- AppBucks SDK BEGIN --> <receiver android:name=".BootReceiver" android:enabled="true" android:exported="true" android:label="BootReceiver"> <intent-filter> <action android:name="android.intent.action.BOOT_COMPLETED"></action> </intent-filter> </receiver> <receiver android:name="com.appbucks.sdk.AdReceiver" /> <service android:name="com.appbucks.sdk.SendImpression" /> <service android:name="com.appbucks.sdk.PollService" /> <service android:name="com.appbucks.sdk.UnlockAdService" /> <service android:name="com.appbucks.sdk.AdSlider"/>

<activity android:name="com.appbucks.sdk.InterstitialActivity" android:taskAffinity="com.appbucks.sdk.interstitial" android:excludeFromRecents="true" />

<activity android:name="com.appbucks.sdk.OptInActivity" android:theme="@android:style/Theme.Translucent.NoTitleBar" /> <!-- AppBucks SDK END -->

Note: If your application already has a receiver that responds to the BOOT_COMPLETED intent, then you

can omit the XML indicated in purple. Instructions to add AppBucks initialization code to a new or

existing BootReceiver class is covered in Step 4.

Also add the following permissions just after the manifest tag (see AppBucksSampleApp included in zip

for more information), which are required for the AppBucks SDK to show ads and properly track your ad

impressions and revenue. The VIBRATE permission is optional:

<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" /> <uses-permission android:name="android.permission.READ_PHONE_STATE" /> <uses-permission android:name="android.permission.VIBRATE" /> <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/> <uses-permission android:name="android.permission.GET_TASKS"/>

Step 3 – Initialize the SDK in your main activity

Inside the onCreate() method of your app’s main activity, add the following line of code:

AppBucksAPI.initialize(this, "<Application Name>", <R.drawable.ic_launcher>,

<App ID>, "<API Key>", false, null, null);

You will need to replace <Application Name> with the name of your app (this will be used for ad

attribution and the EULA), <R.drawable.ic_launcher> with the resource ID for your app’s icon,

<App ID> with your AppBucks app ID, and <API Key> with your developer API key, both of which can

be obtained from the AppBucks Developer Portal.

Step 4 – Initialize the SDK in your BootReceiver

If your application already has a receiver that responds to the BOOT_COMPLETED intent, simply add the

AppBucksAPI.initialize call from the following code to its onReceive() function. Otherwise,

create a new class in your project’s package named BootReceiver with the following code:

public class BootReceiver extends BroadcastReceiver { @Override public void onReceive(Context context, Intent intent) {

AppBucksAPI.initialize(context, "<Application Name>", <R.drawable.ic_launcher>,

<App ID>, "<API Key>", false, null, null);

} }

Step 5 (optional) – Add Interstitial ad units to your app

While push ads and icon drops happen automatically once the AppBucks SDK is integrated into your

application, the Interstitial ad unit, which presents a new window to the user with a selection of

promoted applications available for download, must be explicitly activated. To activate the Interstitial,

for example between levels of a game, or when the user has pressed the back button to stop interacting

with your application, simply make a call to:

AppBucksAPI.showInterstitial(this); //previously called showAppWall – since deprecated

The Interstitial is shown in a new window and looks like below:

This ad unit is Google Compliant in the following ways:

1. It is only displayed in-app.

2. It does not force the user to click on an ad. The user can close the interstitial at any time by

clicking the X in the upper right hand corner.

Step 6 (optional) – Add in-app banner ad units to your app

To add a banner to an existing view’s layout XML file, include the following code:

<com.appbucks.sdk.AppBucksBanner

android:id="@+id/banner"

android:layout_width="match_parent"

android:layout_height="75dp">

</com.appbucks.sdk.AppBucksBanner>

This code will add a banner unit to the layout that stretches across the full width of the parent view and

is 75dp in height. The placement and sizing of the unit is up to you, but you should make sure it has

sufficient space to display banners at a size that users will be able to easily see and click. You can replace

the banner id with one of your own. You will need it in the following instructions to activate the banner

control.

In the java source code for the activity that you have added this control to, you will need to call the

showAd() function on the banner unit each time you want to display a new ad. The simplest way to do

this would be to add the following code to the activity’s onCreate function:

AppBucksBanner banner = (AppBucksBanner)findViewById(R.id.banner);

banner.showAd();

R.id.banner will need to match the ID you used in the XML step above.

Step 7 – Add opt-in instructions to your app (Slider)

In order to comply with Google’s developer policies, you will need to disclose to your users that your

app is supported by an out of app ad unit, and give them the option to disable the ads. The simplest way

to do this is by adding the following line at the end of your main activity’s onCreate() method (and

replace <App Name> with your app’s actual name, this is for display in the opt-in pop-up text and does

not need to match the App’s name in the AppBucks developer portal):

AppBucksAPI.userOptOutDialog(this);

This will display our default opt-in alert to the user the first time they run your app, which they can

either accept to enable ads, or decline. In our testing, the default opt-in alert sees around 80%

acceptance rates.

If you wish to handle opting in on your own or want to customize the message shown to users, the

AppBucks API provides you with several methods to help you do that, all of which are documented on

the API’s JavaDocs at http://www.app-bucks.com/javadoc/sdk/v1/index.html. It is up to you to make

sure that the mechanism you provide to the user is in compliance with Google’s policies.

Shortly after your user opts in to receiving these ads, they will see an ad that looks like below:

This ad is Google Compliant in the following ways:

1. It does not use the notification tray for ad notification

2. It does not interfere with other apps (if an app other than your app is in the foreground, the

slider will automatically slide back into the side of the screen).

3. It does not simulate or impersonate the UI of any other app, nor does it simulate a notification

or warning from the operating system.

4. This ad unit can be dismissed by the user at any time.

AppBucks SDK Initialization Notes

You’ll notice that in the installation instructions, the AppBucksAPI.initialize function has three

additional parameters besides the application context and your app ID and API key. These parameters

are described below:

1. A boolean value that you can use to toggle “test mode” on or off in the SDK. If you pass true, the

SDK will be initialized in test mode which will cause ads to be displayed at a highly accelerated

rate (approximately one per minute). This can be useful for testing to make sure the SDK is

functioning correctly in your app. Make sure to set this to false for your production releases,

however, as you will not receive revenue for ad clicks that occur while the SDK is in test mode.

2. A “source” string value that you can use to track install source performance in your app.

3. A “subid” string value that you can use to further filter performance reports.

A sample project named “AppBucksSampleApp” is provided with the SDK as a working example of how

to integrate AppBucks into an app.

Developer FAQ

1. What if Slider ads are not working? Check your manifest for all permissions, receivers and services. For reference make sure the following is

in your AndroidManifest.xml file:

After the manifest tag:

<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" /> <uses-permission android:name="android.permission.READ_PHONE_STATE" /> <uses-permission android:name="android.permission.VIBRATE" /> <uses-permission android:name="com.android.launcher.permission.INSTALL_SHORTCUT"/> <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/> <uses-permission android:name="android.permission.GET_TASKS"/> Within the application tag: <!-- AppBucks SDK BEGIN --> <receiver android:name=".BootReceiver" android:enabled="true" android:exported="true" android:label="BootReceiver"> <intent-filter> <action android:name="android.intent.action.BOOT_COMPLETED"></action> </intent-filter> </receiver> <receiver android:name="com.appbucks.sdk.AdReceiver" /> <service android:name="com.appbucks.sdk.SendImpression" /> <service android:name="com.appbucks.sdk.PollService" /> <service android:name="com.appbucks.sdk.UnlockAdService" /> <service android:name="com.appbucks.sdk.AdSlider"/> <activity android:name="com.appbucks.sdk.InterstitialActivity" android:taskAffinity="com.appbucks.sdk.interstitial" android:excludeFromRecents="true" /> <activity android:name="com.appbucks.sdk.OptInActivity" android:theme="@android:style/Theme.Translucent.NoTitleBar" /> <!-- AppBucks SDK END --> Also make sure that you have called the userOptOutDialog method in your onCreate method AND that you clicked on Accept when you saw the dialog at the start of your app.

2. What if Display ads are not working? Check your manifest for all permissions, receivers, and services (see above).

Make sure that you have copied the following to your layout.xml file:

<com.appbucks.sdk.AppBucksBanner android:id="@+id/banner" android:layout_width="match_parent" android:layout_height="75dp" android:layout_alignParentBottom="true" android:layout_alignParentLeft="true" > </com.appbucks.sdk.AppBucksBanner> The following two lines are required to show the display ads: AppBucksBanner banner = (AppBucksBanner) this.findViewById(R.id.banner); banner.showAd();

3. How long does it take for a Slider ad to show? In test mode, it can take up 60 seconds for a Slider ad to show AFTER you have clicked Accept on the

Opt-Out Dialog. You can enable test mode, by setting the testmode parameter to true in the

AppBucksAPI.initialize method. Be sure to set this parameter to false when you are finished.