Skip to content
This repository
branch: master
README.md

PlayHaven Android SDK 1.12.5

DEPRECATION NOTICE - October 2013

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.

If you have any questions, visit the Help Center or contact us at support@playhaven.com. We also recommend reviewing our Optimization Guides to learn the best practices and get the most out of your PlayHaven integration.

Table of Contents

Installation

Integrating the PlayHaven Android SDK is dead simple and should take no more than a minute.

Note: The PlayHaven SDK requires a minimum of Android 2.2 (API Level 8). If you are developing for API levels including those below 8 please see the Android developer section here .

Note: If you are developing your game using Unity, this instructions are irrelevant and you should use the PlayHaven Unity SDK located here.

JAR Integration

  1. Download the PlayHaven SDK here and ensure you have the latest version of the Android Developer Tools installed.

  2. Install the SDK into your project.

    1. If a libs folder doesn't already exist, create one in your project root. Android will automatically recognize it.

    2. Drag the PlayHaven SDK JAR file you downloaded into the libs folder. If prompted, select 'Copy files' as opposed to 'Link to files'.

    3. Add the appropriate import statement to your source files:

      import com.playhaven.*;
      
  3. Set the API keys you received from the dashboard. Although you can set these wherever you wish, we advise the root Activity.

    PHConfig.token = "your token";
    PHConfig.secret = "your secret";
    

Make sure prior to compiling that you've imported PHConfig. This may be done by:

 import com.playhaven.src.common.PHConfig;
  1. Add the ad view to your AndroidManifest.xml file.

Note: The activity XML tag must be placed inside the application tag.

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.INTERNET"/>

<activity android:name="com.playhaven.src.publishersdk.content.PHContentView" android:theme="@android:style/Theme.Dialog" android:windowSoftInputMode="adjustResize"></activity>

Usage

This guide assumes you have followed the installation instructions above.

Recording game opens

Purpose: helps the server track game usage.

Notes: Make sure to pass in a Context (usually an Activity) to the PHPublisherOpenRequest constructor.

PHPublisherOpenRequest request = new PHPublisherOpenRequest([your context]);

request.send();

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.

PHPublisherContentRequest request = new PHPublisherContentRequest([your context], "your placement");

request.send();

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.

PHPublisherContentRequest request = new PHPublisherContentRequest([your context], "your placement");
// Set your listeners, we only set the content listener here.
request.setOnContentListener([your content delegate]);
request.preload();

// ...
// ...
// ...

// Elsewhere in the code...
request.send();

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.

PHNotificationView notifyView = new PHNotificationView([your context], "your placement");

[your button/view/layout].addView(notifyView);

notifyView.refresh();

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.

public void unlockedReward(PHPublisherContentRequest request, PHReward reward) {
    ... your handling code here...
}

The PHReward object has the following useful properties:

  • name: The reward's name (specified in the dashboard)
  • quantity: The reward's amount (specified in the dashboard)

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.

PlayHaven offers full-screen content units which advertise virtual goods. When a user clicks an ad, the PlayHaven Android SDK sends a "callback" to your game.

Note: You must configure your "in app purchase" items on the PlayHaven Dashboard after creating them in your Android Market dashboard.

The PlayHaven SDK only handles two elements of a user's complete transaction:

  1. Notifying your game when a user clicks "purchase" in an ad
  2. Tracking the IAP purchase

Note: The PlayHaven Android SDK does not handle interaction with the Android Billing Service as implementation details vary by game. Please refer to the Android Billing Guide for further information.

The first step notifies your game through the PHPublisherContentRequest.PurchaseDelegate interface. You must implement the interface's single method:

public void shouldMakePurchase(PHPublisherContentRequest request, PHPurchase purchase) {
    .... make purchase here .... 
}

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 original shouldMakePurchase(...) 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:

PHPublisherIAPTrackingRequest trackingRequest = new PHPublisherIAPTrackingRequest([your context], purchase)
trackingRequest.send();

Again, you should have a reference to the puchase object from shouldMakePurchase(...).

You're done!

Potential Pitfall: The .reportResolution(...) call must happen before sending the PHPublisherIAPTrackingRequest

Using Connection Targeting

In order to use connection targeting, include the ACCESS_NETWORK_STATE permission in your AndroidManifest.xml file.

    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Tracking User Activity

The PlayHaven Android SDK makes tracking user activity simple. Register an Android activity for tracking by calling PHSession.register([your activity]) in the onResume() handler and PHSession.unregister([your activity]) in the onPause() handler of your activity.

Note: Game opens must be recorded for user activity tracking to function (see Recording Game Opens).

Note: Include the unregister() and register() calls in all relevant activities.

@Override
protected void onResume() {
    super.onResume();
    PHSession.register(this);

    ... your code here ...
}

@Override
protected void onPause() {
    super.onPause();
    PHSession.unregister(this);

    ... your code here ...
}

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:

PHPublisherOpenRequest request = new PHPublisherOpenRequest([your context]);
request.delegate = [your delegate (usually an Activity)]
request.send();

PHPublisherContentRequest delegates

Note: There are several delegate interfaces for a PHPublisherContentRequest. You should implement those which provide relevant callbacks.

  1. FailureDelegate
  2. CustomizeDelegate
  3. RewardDelegate
  4. ContentDelegate
  5. PurchaseDelegate

When working with the multiple delegates in PHPublisherContentRequest:

PHPublisherContentRequest request = new PHPublisherContentRequest([your context (usually Activity)], "your placement");
request.setOnFailureListener([your failure delegate]);
request.setOnCustomizeListener([your customize delegate]);
request.setOnRewardListener([your reward delegate]);
request.setOnContentListener([your content delegate]);
request.setOnPurchaseListener([your purchase delegate]);
request.send();
  • failure of request. This method is equivalent to the contentDidFail handler, you can implement either:
public void didFail(PHPublisherContentRequest request, String error) {
    ... your handling code here ...
}
  • failure of actual ad. This method is equivalent to the didFail handler, you can implement either):
public void contentDidFail(PHPublisherContentRequest request, Exception e) {
    ... your handling code here ...
}
  • customize the close button:
public Bitmap closeButton(PHPublisherContentRequest request, PHButtonState state) {
    ... return a custom bitmap for the given state ...
}
  • customize the border color:
public int borderColor(PHPublisherContentRequest request, PHContent content) {}
    ... constant from Color ...
}
  • clicked on a VGP ad:
public void shouldMakePurchase(PHPublisherContentRequest request, PHPurchase purchase) {}
    ... make the purchase via the Android Billing Service ...
}
  • unlocked a reward:
public void unlockedReward(PHPublisherContentRequest request, PHReward reward) {
    ... handle the reward in-game ...
}
  • make a purchase after user clicks ad:
public void shouldMakePurchase(PHPublisherContentRequest request, PHPurchase purchase) {
    ... make the real purchase through Android Billing ...
}
  • ad content is downloading:
public void willGetContent(PHPublisherContentRequest request) {
    ... your handling code here ...
}
  • ad content is going to display:
public void willDisplayContent(PHPublisherContentRequest request, PHContent content) {
    ... return a custom bitmap for the given state ...
}
  • ad content has been shown:
public void didDisplayContent(PHPublisherContentRequest request, PHContent content) {
    ... your handling code here ...
}
  • ad was dismissed:
public void didDismissContent(PHPublisherContentRequest request, PHDismissType type) {
    ... your handling code here ...
}

PHPublisherOpenRequest delegates

  • successful request callback:
public void requestSucceeded(PHAPIRequest request, JSONObject responseData) {
    ... your handling code here ...
}
  • unsuccessful request callback:
public void requestFailed(PHAPIRequest request, Exception e) {
    ...your handling code here...
}

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:

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

    System.out.println("Resumed after other app was shown");
}

Integration Test Console Overview

PlayHaven provides an Integration Test Console. It's located at http://console.playhaven.com

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

git clone https://github.com/playhaven/sdk-android.git
cd sdk-android
mvn install 
ls api/target/

In Eclipse

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

  1. Clone the sdk-android repository.

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

  3. 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".

  4. 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.

  5. Build

    1. In the playhaven Eclipse project, open pom.xml. Add the following snippet inside the <build> element:
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.eclipse.m2e</groupId>
                <artifactId>lifecycle-mapping</artifactId>
                <version>1.0.0</version>
                <configuration>
                    <lifecycleMappingMetadata>
                        <pluginExecutions>
                            <pluginExecution>
                                <pluginExecutionFilter>
                                    <groupId>net.mgorski.quicktag</groupId>
                                    <artifactId>quicktag</artifactId>
                                    <versionRange>[2.1.2,)</versionRange>
                                    <goals>
                                        <goal>quicktag</goal>
                                    </goals>
                                </pluginExecutionFilter>
                                <action>
                                    <execute />
                                </action>
                            </pluginExecution>
                        </pluginExecutions>
                    </lifecycleMappingMetadata>
                </configuration>
            </plugin>
        </plugins>
    </pluginManagement>
  1. Now right-click on the project in the Package Explorer and select Maven > Update Project.
  2. 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.
  3. Select "Run As" > "Maven install".

Your jar should be in api/target/.

Something went wrong with that request. Please try again.