Pixalate Pre-Bid Fraud Blocking SDK for Android

The Pixalate Pre-Bid Blocking SDK provides easy an easy implementation of Pixalate's Pre-Bid Fraud Blocking API in your Android application.

Installation & Integration

Maven Central

// build.gradle
dependencies {
  implementation 'com.pixalate.android:prebid-blocking:0.1.0'
}

<!-- pom.xml -->
<dependency>
  <groupId>com.pixalate.android</groupId>
  <artifactId>prebid-blocking</artifactId>
  <version>0.1.0</version>
  <type>aar</type>
</dependency>

The latest version of the pre-built SDK is available in Maven Central, and can be integrated into your project's build.gradle, or directly in your pom.xml.

Authentication & Basic Configuration

// in your app initialization code, such as MainActivity.java
// A sample configuration & initialization -- the values chosen for this example
// are not meaningful.
BlockingConfig config = new BlockingConfig.Builder("your-api-key-goes-here")
    .setBlockingThreshold(0.8)
    .setTTL(1000 * 60 * 60 * 7)
    .setRequestTimeout(3000)
    .build();

PixalateBlocking.initialize(this, config);

To use the Pixalate Blocking SDK, you must first initialize it. You can do this by calling PixalateBlocking.initialize() and passing in a configuration object.

The configuration builder allows you to override the default configuration values:

Blocking Ads

// The most basic blocking request, displaying 
// all possible interface implementations.
// You only need to implement the methods you need for your use case.
PixalateBlocking.requestBlockStatus(new BlockingStatusListener () {
    @Override
    public void onAllow () {
      /* Load your ads here! */
    }

    @Override
    public void onBlock () {
      /* Log the event, or otherwise modify your app behavior accordingly. */
    }

    @Override
    public void onError (int errorCode, String message) {
      /* In the case of an unexpected error, it is recommended to
          loading ads here as well. */
    }
});

Once the SDK is set up, you can implement it into your ad loading logic. The SDK is framework and approach-agnostic.

The basic pattern for performing a block request is as follows. All listener methods are optional, but at the very least you should implement onAllow.

Testing Responses

// Pass the blocking mode as the first parameter to simulate different blocking conditions.
PixalateBlocking.requestBlockStatus(
  PixalateBlocking.BlockingMode.ALWAYS_BLOCK,
  new BlockingStatusListener () {
    /* ... */
  }
);

During development, it may be helpful to test both blocked and unblocked behavior. You can accomplish this using the alternate overload for Pixalate.requestBlockStatus that includes a BlockingMode parameter. You can pass BlockingMode.DEFAULT to use normal behavior, BlockingMode.ALWAYS_BLOCK to simulate a blocked response, or BlockingMode.NEVER_BLOCK to simulate a non-blocked response:

Debug mode requests execute normally except that they do not perform a real API call, and so can be used to test custom blocking strategies as well.

Logging

PixalateBlocking.setLogLevel( PixalateBlocking.LogLevel.DEBUG );

The SDK supports multiple logging levels which can provide additional context when debugging. The current level can be set through Pixalate.setLogLevel, and defaults to INFO. Logging can be disabled entirely by setting the level to NONE.

Advanced Configuration

Blocking Strategies

Pixalate provides default strategies for both the device ID and IPv4 address parameters. These values should cover most common use cases.

If for any reason you wish to add, remove, or modify the blocking strategies used by the library, you can create a custom strategy. This is explained in more detail below.

Device ID

If your app uses Google Play Services, this strategy will read the device's Advertising ID. Otherwise, it will attempt to retrieve the device ID from Telephony.getDeviceId(), a method only valid on older phones. If this fails, it will return the value of Settings.Secure.ANDROID_ID hashed using MD5. Check out the Fraud API documentation for more information about possible values.

IPv4 Address

The SDK will retrieve the external IPv4 address of the device by utilizing a Pixalate endpoint.

User Agent

Although the pre-bid fraud API supports passing browser user agents, the concept of a user agent is nebulous when in an app context. For this reason, the default blocking strategy does not utilize user agents.

Parameter Caching

// Override the TTL of the default blocking strategy when constructing 
// the blocking config object if you want to set it to something 
// different than the global configuration's TTL.
BlockingConfig config = new BlockingConfig.Builder("my-api-key")
    .setBlockingStrategy(new DefaultBlockingStrategy(1000 * 60 * 5))
    .build();

The default blocking strategy has utilities for caching the parameters it retrieves. By default, it will mirror the TTL of the global configuration. This value can be overridden by passing a new DefaultBlockingStrategy object to the BlockingConfig.Builder, as shown in the snippet.

Custom Blocking Strategies

If you have an alternate use case that the default strategies are not providing, you would like more control over how you retrieve the blocking parameters, or if you want to add or remove included parameters, you can create your own blocking strategy.

Overriding DefaultBlockingStategy

// TestBlockingStrategy.java
static class TestBlockingStrategy extends DefaultBlockingStrategy {
    @Override
    public String getIPv4Impl (Context context, BlockingStrategyCallback callback) {
        callback.done(null);
    }
}

// Then, in your initialization code, pass your modified strategy
// into the setBlockingStrategy builder method.
BlockingConfig config = new BlockingConfig.Builder("my-api-key")
    .setBlockingStrategy(new TestBlockingStrategy())
    .build();

The simplest method is to extend DefaultBlockingStrategy, which carries over all default behavior, including caching.

When extending the DefaultBlockingStrategy, make sure to override the -Impl variety methods rather than the base methods so as to preserve caching behavior.

Creating a Strategy From Scratch

// CustomBlockingStrategy.java

// A contrived custom strategy only implementing the IPv4 parameter --
// all other parameters will be null by default.
static class CustomBlockingStrategy extends BlockingStrategy {
    @Override
    public String getIPv4 (Context context, BlockingStrategyCallback callback) {
        // The strategy implementations are executed in a background thread, so it is OK 
        // to use blocking operations such as HttpsURLConnection.

        URL url = new URL("some-ipv4-source-url");

        HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();

        connection.setRequestMethod("GET");

        int connStatus = connection.getResponseCode();

        String ipv4 = /* do something with the response to extract IPv4... */;

        callback.done( ipv4 );
    }
}

// Then, in your initialization code, pass your modified strategy
// into the setBlockingStrategy builder method.
BlockingConfig config = new BlockingConfig.Builder("my-api-key")
    .setBlockingStrategy(new CustomBlockingStrategy())
    .build();

To create a custom strategy from scratch, you must extend the BlockingStrategy interface. All of the methods have default implementations returning null, meaning you only need to override the strategies you want to provide values for.

Important note: To keep the core functionality as implementation agnostic as possible, default strategy caching behavior is implemented in DefaultBlockingStrategy. If you implement your own blocking strategy from scratch using the BlockingStrategy interface, you will need to manage your own caching of parameters. However, the caching of API responses is always managed by the SDK, and is unaffected by the blocking strategy.