README.md

PlayHaven Android SDK 1.12.5

The PlayHaven Android SDK 1.12.5 has been deprecated. We will continue to support games currently integrated with Android SDK 1.12.5 until October 2014.

Please use the new Android SDK (version 2), which was built from scratch to enhance performance and functionality, and is loaded with new features like support for push notifications.

PlayHaven is a mobile game LTV-maximization platform which helps you take control of the business of your games.

Acquire, retain, re-engage, and monetize your players with the help of PlayHaven's powerful marketing platform. Integrate once and embrace the flexibility of the web as you build, schedule, deploy, and analyze your in-game promotions and monetization in real-time through PlayHaven's easy-to-use, web-based dashboard.

An API token and secret is required to use this SDK. These tokens uniquely identify your app to PlayHaven and prevent others from making requests to the API on your behalf. To get a token and secret, please visit the PlayHaven Dashboard.

Displaying Content

Purpose: Displays a fullscreen content unit with the placement specified. Content units include ads, announcements and cross-promotions. Please see here for a complete list of content units PlayHaven has available.

Notes: Make sure to provide the PHPublisherContentRequest constructor with a valid Context (usually an Activity). You can specify placements in the PlayHaven dashboard.

Notes: If you wish to display a content unit when an activity loads it is recommended that you do so by placing it in the onResume method of the Activity. This will cause the content unit to be displayed whenever the Activity comes to the foreground. This allows for maximum flexibility in tuning the display of the content unit.

Optimizing for Performance

The PlayHaven SDK will automatically download and store a number of content templates after a successful PHPublisherOpenRequest (see Recording Game Opens).

To further improve the responsiveness of your ads, you may choose to preload a content unit for a given placement. To do so, simply call preload() to start the network request without displaying the advertisement. When you are prepared to display the advertisement, call send() as usual. This feature is especially important for slow mobile data connections.

Displaying a notification badge

Purpose: Displays a small badge with a number indicating the number of new games a user can view.

Notes: You may place this anywhere in your app but we've found the best solution is to add it to an button which then launches a PHPublisherContentRequest with a "more_games" placement. Once a user clicks on the button you should call clear() on the notification view to reset the badge number.

Unlocking Rewards

Purpose: Allows your game to respond when the users unlocks rewards you have configured in the dashboard.

Notes: You must implement the PHPublisherContentRequest.RewardDelegate interface, and set the delegate object on a PHPublisherContentRequest object in order to receive this callback. This requires implementing the method unlockedReward in your delegate object. See the Callbacks section below for more information.

Handling Virtual Goods Purchases

The PlayHaven Android SDK supports "virtual good promotion" (or VGP) which allows you to advertise virtual products available within a game. For example, your puzzle game may offer additional levels or special "skins" for a nominal fee.

In this callback, you should complete the actual transaction through the Android Billing Service. You should also save a reference to the PHPurchase object for later use.

The PlayHaven Android SDK simply adds an intermediate step to the transaction process:

Once the Android Billing Service has confirmed (or canceled) the user's purchase, you must call:

purchase.reportResolution([purchase resolution], [your activity]);

on the purchase object passed into the originalshouldMakePurchase(...) callback. Your reported resolution should correspond to the result of the Android Billing transaction (canceled, completed, failed, etc.) along with a valid Context.

Finally, you must report the "in app purchase" transaction to the sever with a PHPublisherIAPTrackingRequest:

Callbacks

Every type of request in the PlayHaven Android SDK has a special "delegate" which may be set to receive "callbacks" as the request progresses. You can find more information regarding the delegate pattern here.

You must implement the appropriate delegate interface from the list below and then add your object as a delegate. Most often the root Activity should handle the callbacks.

Once you've implemented the appropriate callbacks you must set the delegate on the individual request before sending:

Tips and Tricks

A few helpful tips on using the PlayHaven Android SDK.

didDismissContentWithin(timerange)

This special method within PHPublisherContentRequest is helpful when you wish to determine if your game is resuming after showing an ad or from another app entirely. The timerange argument should be specified in milliseconds and we generally find that about 2 seconds (2000 milliseconds) works best. An example onResume handler using this feature:

@Overridepublicvoid onResume() {
super.onResume();
if (PHPublisherContentRequest.didDismissContentWithin(2000)) { // can actually be less than 2 seconds, all we want is enough time for onResume to be calledSystem.out.println("Resumed after displaying ad unit");
return;
}
System.out.println("Resumed after other app was shown");
}

Integration Test Console Overview

At the Testing Console, developers can enter their Android device ID. The Testing Console listens for events coming from the test device and displays a log of output, including successes, failures, and helpful information. The test device must be registered as test device from the PlayHaven Dashboard and "enabled" via the Publisher Dashboard.

Currently one cannot "export" their console log but you can copy and paste it into a text file or spreadsheet. To search, please use Command+F.

To begin, enter your Android device ID and follow the "Testing Instructions" in the light blue box to view events and comments.

The following can currently be checked:

Upon Open Request:

Device ID (Android device ID)

Open requests sent

Token/secret present

SDK Version

Placements:

Placement detection (Content request)

Pre-loading (Pre-loading request)

IAP:

Check that pricing is present (IAP transaction request)

Building The SDK

You do not need to build the SDK in order to use it. Precompiled version are available on the PlayHaven website. However, if you desire to modify the SDK for your own use, you may do so. The SDK uses the Maven build system, which is usually pre-installed on OSX and may be installed in Linux or Windows. Many IDEs also have plugins for Maven; the instructions for using Eclipse are included below.

Note: Before you begin, be sure that the Android SDK has been installed properly and that your ANDROID_HOME environment variable exists.

In Linux or OSX

In Eclipse

Note: Before you begin, be sure that the ADT plugin for Eclipse has been configured properly.

Clone the sdk-android repository.

Install m2e. m2e allows you to build Maven projects in Eclipse. It can be installed from the Eclipse Marketplace as "Maven Integration for Eclipse".

Install m2e-android. This connector allows you to build Android Maven projects in Eclipse using m2e. It can be installed from the Eclipse Marketplace as "Android Configurator for M2E".

In Eclipse, select "File > Import > Maven > Existing Maven Projects" and open the root folder of the cloned repository. You should see two pom.xml configurations available. Check both boxes. If this is your first time opening a Maven project, it might take several minutes to download and install all the neccesary Maven artifacts. Click Next, then Finish. It may prompt you to install other m2e connectors; if it does then these are necessary. There will be an "Plugin execution not covered" error about quicktag, you'll fix that next.

Build

In the playhaven Eclipse project, open pom.xml. Add the following snippet inside the <build> element:

Now right-click on the project in the Package Explorer and select Maven > Update Project.

The m2e plugin may incorrectly set your Java Compiler level for the project. If it does, there will be errors regarding the @Override annotation. Edit the project properties > Java Compiler options to use a JDK Compliance level of 1.6 or greater.