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 ImportGeneralFile 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 projects 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 projects 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 apps 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 apps 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 projects 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 views 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 activitys 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 Googles 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 activitys onCreate() method (and
replace <App Name> with your apps actual name, this is for display in the opt-in pop-up text and does
not need to match the Apps 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 APIs 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 Googles 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
Youll 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.