Adzerk Android SDK

An Android SDK for the Adzerk Native and UserDB APIs

Download

Grab via gradle

implementation 'com.adzerk:sdk:3.0.+'

The SDK uses Java 17 and supports a minimum Android 5.1 (API level 22).

Usage

Create an instance of the AdzerkSdk for your networkId:

AdzerkSdk sdk = new AdzerkSdk.Builder().networkId(23L).build();

Create an instance of the AdzerkSdk and also provide a hostname:

AdzerkSdk sdk = new AdzerkSdk.Builder().networkId(23L).hostname("custom.host.com").build();

Build a request for placements

Request request = new Request.Builder()
      .addPlacement(new Placement("div1", <site_id>, <ad_types...>))
      .addPlacement(new Placement("div2", <site_id>, <ad_types...>))
      .addPlacement(new Placement("div3", <site_id>, <ad_types...>))
      .build();

Submit the request and get a callback for the response

sdk.requestPlacement(request, listener);

Get content and decisions from the response

@Override
public void success(Response response) {
    Decision firstDecision = response.getDecisions("div1").get(0);
    // ...
}

@since SDK v2.2.0+

Recording Impression & Clicks

Use with the fetch ad example above.

// Impression pixel; fire when user sees the ad
String impUrl = decision.getImpressionUrl();
sdk.firePixel(impUrl, listener);

// Click pixel; fire when user clicks on the ad
String clickUrl = decision.getClickUrl();
sdk.firePixel(clickUrl, listener);

Modifying the revenue

// Click pixel; fire when user clicks on the ad and modify the click revenue
//   OVERRIDE: replaces the revenue value of the click/event
//   ADDITIONAL: adds the specified value to the original revenue value of the click/event
String clickUrl = decision.getClickUrl();
sdk.firePixel(clickUrl, revenue, RevenueModifierType.OVERRIDE, null, listener);

Setting the gross merchandise value for the event.

// Click pixel; fire when user clicks on the ad and modify the click revenue
//   OVERRIDE: replaces the revenue value of the click/event
//   ADDITIONAL: adds the specified value to the original revenue value of the click/event
String clickUrl = decision.getClickUrl();
Float grossMerchandiseValue = 1.5f;
sdk.firePixel(clickUrl, revenue, RevenueModifierType.ADDITIONAL, grossMerchandiseValue, listener);

Handle the fire pixel response

// status: HTTP status code
// location: click target URL
@Override
public void success(FirePixelResponse response) {
   Log.d(TAG, "Fired! " +
      "status: " + response.getStatusCode() + " " +
      "location: " + response.getLocation());
}

Additional Options

Additional optional parameters supported by the API may be specified via the Builder on the Request or Placement.

Example: to specify eCPM partitions for a Placement:

String[] ecpmPartitions = new String[]{"main", "detail", "footer"};
Request request = new Request.Builder()
    .addPlacement(new Placement("div1", 1133898L, 163)
        .setCount(ecpmPartitions.length)
        .addAdditionalOption("ecpmPartitions", ecpmPartitions))
    .build();

@since SDK v2.1.0+

Distance Targeting

Distance Targeting is supported via Additional Options on the request.

val request = new Request.Builder()
    .addPlacement(Placement("div1", 1133898, (163)))
    .addAdditionalOption("intendedLatitude", 35.91868)
    .addAdditionalOption("intendedLongitude", -78.96001)
    .addAdditionalOption("radius", 50)
    .build()

Multi-Winner Placements

A multi-winner placement returns multiple selections inside a single placement object.

To request multiple winners, specify a count for the Placement object. This requests the maximum number of winners (selections) that can be included in the placement.

Request request = new Request.Builder()
   .addPlacement(new Placement("div1", <site_id>, <ad_types...>).setCount(3))
   .build();

@since SDK v2.0.0+

GDPR Consent

Consent preferences can be specified when building a request. For example, to set GDPR consent for tracking in the European Union (this defaults to false):

Request request = new Request.Builder(placements)
    .setUser(new User(key))
    .setConsent(new Consent(true))
    .build();

@since SDK v0.4.0+

Building

Use gradlew to build library archive

./gradlew assemble

output: sdk/build/outputs/aar

Testing

Run unit tests

./gradlew test --rerun-tasks

Specify --rerun-tasks to rerun up-to-date tests. To view test reports see:

output: sdk/build/reports/tests

Documentation

Generate the SDK documentation

./gradlew javadoc

output: sdk/build/docs/javadoc

Publishing

Publishing to Maven Central is automated via GitHub Actions. When a new GitHub release is created, the publish workflow will build, sign, and publish the package to Sonatype OSSRH. The version is derived from the release tag name.

The workflow requires the following repository secrets:

• GPG_KEY_BASE64 - base64-encoded GPG signing key
• GPG_PASSWORD - passphrase for the GPG key
• NEXUS_USERNAME / NEXUS_PASSWORD - Sonatype OSSRH credentials

To publish to local Maven repository for testing:

./gradlew publishToMavenLocal

Login to Sonatype OSSRH, locate the staging package, and release it.