Yieldprobe SDK Android Sample Application

This repository contains:

• The Yieldprobe Sample Application referencing the SDK from JCenter.

For the SDK source look into the other SDK repository.

Additional documentation:

• Sample Application Guide.
• Integration Guide for the SDK into your application.

Sample Application Guide

Table of Contents

1. Actions
2. Screenshots

1. Actions

The Yieldprobe Sample Application calls the API from Kotlin as well as Java in two separate activities. It does extensive error handling.

You can do the following actions inside the application:

• Initialization
  • Check for Google Play Services availability. They are needed for IDFA (ID for Advertiser) and Geolocation readout. It will check at runtime for enabled services. See the screenshots below.
  • Initialize the SDK (use checkboxes to set Geolocation and PersonalizedAds).
  • Check the initialization status of SDK.
• Configuration
  • Set configuration (use checkboxes to set Geolocation and PersonalizedAds).
  • Get the current configuration.
  • Get device metadata.
• Probe requests and targeting
  • Select three predefined test adslots or provide your own ones and do a probe request over the EventBus or Futures API (works only on devices with API level 24 and above).
  • Do three probe requests in parallel (predefined adslots).
  • View the last targeting response.
• Advertisement targeting
  • Provide targeting to the Adition SDK and display an advertisement.
• Permissions and logging
  • Check and request the location permissions.
  • See a log of the Yieldprobe SDK.

2. Screenshots

Integration Guide

Table of Contents

1. Introduction
2. Dependencies and Manifest
3. Initialization of SDK
4. Configuration Updates
5. Probe Request to get Targeting
   1. CompletableFutures API
   2. EventBus API
6. Show Advertisements with Adition SDK
7. Compilation and ProGuard
8. Logging and Exceptions

1. Introduction

This section describes the integration process of the Yieldlab Yieldprobe SDK for Android. Read through this guide to integrate the SDK into your application. You can always take a look into the complete sample application called Yieldprobe Sample Application to see the SDK usage from Kotlin or Java.

The code snippets are taken out of the files AndroidManifest.xml, build.gradle, ActivitySDKKotlin.kt and ActivityAd.kt. The code is shown in Kotlin only. There is always the equivalent snippet in ActivitySDKJava.java.

For complete documentation of all exposed functions and data types see the generated SDK documentation.

2. Dependencies and Manifest

The library is available from JCenter. Update the dependencies in your build.gradle file. The SDK was verified with the library versions below.

Your minSDK version can not be lower than API level 16. API levels under 16 are not supported by the SDK.

compileSdkVersion 29
defaultConfig {
    minSdkVersion 16
    targetSdkVersion 29
}


dependencies {
    // needed for SDK to work
    implementation 'org.greenrobot:eventbus:3.1.1'
    implementation 'com.google.android.gms:play-services-location:17.0.0'
    implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'
    implementation 'com.squareup.okhttp3:okhttp:4.2.0'
    implementation 'com.google.code.gson:gson:2.8.6'
    // the library itself from JCenter
    implementation 'com.yieldlab.yieldprobe:yieldprobe:1.0.0'
}

The SDK needs certain permissions to be added in your AndroidManifest.xml. It is very likely your application already uses these.

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

The location permissions needs a runtime confirmation by the user.

See the sample code in how to request these permission. The relevant functions are checkPermissionsAndRequest() and onRequestPermissionsResult().

3. Initialization of SDK

First, you should check for Google Play Services availability before initializing the SDK.

// check for Play Services. Do not show a popup for user if not enabled.
val available = Yieldprobe.isGooglePlayServicesAvailable(this, false)

The SDK is configured over a Configuration object. See the data class definition below.

data class Configuration(
    var mGeolocation: Boolean = false,
    var mUsePersonalizedAds: Boolean = true,
    var mRequestTimeoutInMs: Long = Yieldprobe.DEFAULT_HTTP_CONNECTION_TIMEOUT_IN_MS,
    var mAppName: String? = null,
    var mBundleName: String? = null,
    var mStoreURL: String? = null,
    var mExtraTargeting: Map<String, String?>? = null
)

The SDK has to be initialized once with Yieldprobe.initialize() for the lifetime of your application. Make sure to pass the ApplicationContext, not the Activity / Fragment Context.

Kotlin call with default parameter naming in configuration object.

try {
    val configurationDefault: Configuration =
        Configuration(
            true, 	// Geolocation enabled
            true, 	// PersonalizedAds enabled
        )
    Yieldprobe.initialize(applicationContext, this, configurationDefault)
} catch (e: Exception) {
    e.printStackTrace()
}

4. Configuration Updates

You can update the configuration after initialization during runtime with Yieldprobe.configure().

try {
    val configurationNew: Configuration =
        Configuration(
            false, 	// Geolocation disabled
            false, 	// PersonalizedAds disabled
        )
    Yieldprobe.configure(applicationContext, this, configurationNew)
} catch (e: Exception) {
    e.printStackTrace()
}

5. Probe Request to get Targeting

To get targeting for adslots call the Yieldprobe.probe() or Yieldprobe.probeWithEvents() functions with a single Int or a Set<Int>.

var singleAdslot: Int = 123456
var setOfAdslots: Set<Int> = setOf(123456, 234567, 345678)

The API is asynchronous. It will respond after the request is completed with a single Bid or a HashMap<Int, Bid>.

data class Bid (
    var timestamp: String? = null,
    var id: String? = null,
    var customTargeting : MutableMap<String, Any?> = mutableMapOf<String, Any?>()
)

• The API implements a connection timeout for the HTTP client connection time. The default value is set to 10.000 ms from Yieldprobe.DEFAULT_HTTP_CONNECTION_TIMEOUT_IN_MS.
• The API supports requests in parallel. You can issue multiple requests and will be notified for each with a separate response.
• Please be aware of the implications of different API levels of minSDK for the API to choose from. There are two API options.

5.i CompletableFutures API

You can use the CompletableFutures API if your minSDK is equal or above API level 24.

A sample call in Kotlin.

// A sample call with a set
var setAdslots = SetOf(1233, 2334, 45343)
Yieldprobe.probe(setAdslots).thenApply {
    // var it contains the response HashMap
}.exceptionally { e ->
    e.printStackTrace()
}

5.ii EventBus API

Otherwise, you have to use the EventBus API. It most cases you want to use this API because it is downwards compatible with API level 16.

You also have to register to the Events. EventBus setup inside of Activity or Fragment lifecycle functions.

public override fun onStart() {
    super.onStart()
    EventBus.getDefault().register(this)
}

public override fun onStop() {
    super.onStop()
    EventBus.getDefault().unregister(this)
}

Subscription to Events

@Subscribe(threadMode = ThreadMode.MAIN)
fun onMessageEvent(event: EventProbeSuccess) {
    // do something with the response in event.getBids()
}

@Subscribe(threadMode = ThreadMode.MAIN)
fun onMessageEvent(event: EventProbeFailure) {
    // do something with the message in event.getMessage()
}

The EventBus call

try {
    val setAdslots = SetOf(1233, 2334, 45343)
    Yieldprobe.probeWithEvents(setAdslots)
    // SDK will answer with EventProbeSuccess or EventProbeFailure
} catch (e: Exception) {
    e.printStackTrace()
    addToLog(e.toString())
}

6. Show Advertisements with Adition SDK

To show an advertisement look into the file ActivityAd.kt and the function setupAditionAdView() how to set up the AditionView from Adition SDK with targeting.

7. Compilation and ProGuard

If you use ProGuard include these statements.

-keep class Yieldprobe.*
-dontwarn okio.**
-keep class com.google.android.gms.** { *; }
-dontwarn com.google.android.gms.**

8. Logging and Exceptions

You can receive logging messages from the SDK over EventBus.

@Subscribe(threadMode = ThreadMode.MAIN)
fun onMessageEvent(event: EventProbeLog) {
    // read out event.getMessage()
}

The SDK reports wrong function calls (e.g. wrong order, wrong arguments, network errors) over exceptions to the user.