This Android library enables the usage of tracking events via Topspin. It’s distributed via Packagecloud as a binary library for inclusion in Android apps. Ask your Topspin contact for a read token to access the Packagecloud repository.

Quick start

  • Obtain a read token for PackageCloud repository by following the instructions (Maven Repository Install Instructions) in the package home page if you have access to the package, otherwise ask

  • Add the Topspin library as a dependency of your application:

    repositories {
       maven {
         url "<PACKAGECOULD_READ_TOKEN>/npo-data/android-tagging-sdk/maven2"
       // If you use the AT Internet backend
       maven {
          url ""
    dependencies {
        compile 'nl.npo.topspin:topspin-android:<latest-version>'
        // If you use AT Internet, check github SDK repo for compatible version
        implementation 'com.atinternet:Tracker:<version-from-github-here>'
  • Make sure the following permissions are requested in your manifest file:

    • android.permission.INTERNET
    • android.permission.ACCESS_NETWORK_STATE (if you use AT Internet)
  • Initialize Topspin library in your Application subclass.

    public class TestApp extends Application {
       public void onCreate() {
          // Create a Topspin instance with 2 plugins (backends)
          // NOTE: replace DEV with PREPROD/PROD depending on the 
          // version of the app (ie. using BuildConfig).
          Topspin.Builder builder = Topspin.builder(this);
          Topspin topspin = builder.withPlugins(
                 new DivoltePlugin.Builder(Environment.DEV)
                 new AtInternetPlugin.Builder(Omgeving.DEV)
          // Set application wide labels (optional)
          PageLabels labels = topspin.getPageLabels();
          labels.merkId = 3; // nosop3
          labels.merk = "nosop3";
          labels.platform = Platform.APP;
          labels.merkType = MerkType.STANDALONE;
          labels.platformVersie = BuildConfig.VERSION_NAME;
          labels.noboEventType = NoboEventType.HOME;
          labels.noboMediaType = NoboMediaType.GENERAL;
          labels.omroepLabel1 = "omroep-specifiek-1";
          // Store instance for easy access
          // Register app to automatically send
          // app-lifecycle events
  • In a specific screen (activity or fragment) that you want to use for page tracking, add code like this:

    public class MainActivity extends Activity {
       Tracker mTracker;
       protected void onCreate(Bundle savedInstanceState) {
          // page view, inheriting global labels from app
          mTracker = TopspinInstance.get().createTracker();
          // set required labels for a page
          // perform actual pageview
             // optional: referrer
  • To record more events from the same page, re-use the Tracker:

    public void onButtonClicked() {
        mTracker.customEvent("buttonClicked", CustomEventType.Action)

Media streams

For recording stream events, create a StreamTracker from the tracker:

public void startPlayback() {
   mStreamRecorder ="KNO_2308383");


   // when the video stars:
   // mStreamRecorder.start(0);

public void pause() {

A real-world player would add various callbacks to the player which call the corresponding methods on the StreamRecorder.

Recommendation offers / choices

Following the general Topspin design, there are three types of recommendations: editorials, recommendations and searches. For each of the types, a specific tracker can be created from your main Tracker object.

For detailed information about recommendation fields, see the general Topspin documentation for recommendations.

Profile data

To add NPO user profile data to the gathered analytics, call mTracker.login() and mTracker.logout() when appropriate. The login data is not stored by the library, and must be properly set each time the library is initialized.

After a login call, all events will contain a reference to the profile.


If your app includes OkHttp (or another networking library based on top of OkHttp), the library will use that library. NOTE: for OkHttp 2.x, use only version 2.4 or higher.

If the OkHttp library is not found, the library uses HttpURLConnection; this implementation is much less efficient and we advise you to use OkHttp.

Also, a custom Connector can be used to integrate with your favorite network library.


Since version 1.7.0, a random nmoPanelID is generated. This is automatically send to ATInternet (if enabled) as custom var 17. You can get this parameter on the main Topspin object: topspin.getNmoPanelId(). This ID is used for panel identification purposes.

Update instructions

To versoin 1.7.0

No changes required, version 1.6.0 can just be replaced with this one.

To version 1.6.0

  1. Obtain a read token for PackageCloud repository by following the instructions (Maven Repository Install Instructions) in the package home page if you have access to the package, otherwise ask
  2. Change the maven url to “<PACKAGECOULD_READ_TOKEN>/npo-data/android-tagging-sdk/maven2” and get rid of the credentials field

To version 1.5.0

  1. Change Topspin initialisation code to match the code fragment above. For this library version, you’ll need to specify which plugins (backends) to use.
  2. If you use the AT Internet plugin, android.permission.ACCESS_NETWORK_STATE to the app’s manifest.
  3. Change/rename the app’s base label set to match the new page labels.
  4. Change the per-page labels to match the new page label names.

To version 1.4.0

  1. Add code to the app-wide Topspin initialisation code:

  2. Use Tracker.editorials(), and Tracker.push() to create trackers for editorials, search queries and push messages

  3. Use StreamTracker.streamExternal() when playback switches to an external playback device, like Chromecast.

Release notes

Version 1.7.0

  • Added nmoPanelId property on Topspin.

Version 1.6.0

  • Move maven repository from Bintray (deprecated) to Packagecloud
  • Repo now requires authentication when downloading using a Token

Version 1.5.4

  • AT Internet: remove userId from AT Internet attributes
  • AT Internet: fix usage of UUID instead of Google Advertising ID
  • AT Internet: remove preprod environment

Version 1.5.3

  • Update AT Internet configuration (pixelPath, identifier)

Version 1.5.2

  • Update AT Internet configuration (log, domain)

Version 1.5.1

  • Measurement fixes

Version 1.5.0

  • Plugin architecture [TAS-23]
  • Added: AT Internet plugin

Version 1.4.0, Sep 20, 2017

  • Add editorials tracker [TAS-2]
  • Add app start/stop events [TAS-3]
  • Add search tracker [TAS-5]
  • Add push messages tracker [TAS-7]
  • Stream recorder: add event for external playback [TAS-8]
  • Content ID is now optional [TAS-11]

Version 1.3.0, Mar 17, 2017

  • Add recommendations
  • Add login/logout

Version 1.2.1, Dec 5, 2016

  • Fix Divolte ID generation: use base36 instead of base64
  • Only support OkHttp2 for versions 2.4 and up

Version 1.2.0, Nov 7, 2016

  • Refactor library
  • Add Stream Tracker

Version 1.1.0, June 29, 2016

  • Adds support for submitting Stream Events
  • Adds support for submitting Recommendation Events

Version 1.0.1, June 17, 2016

  • Bug fix: divolte-collector requires the application/json Content-Type to come without the encoding parameter.

Version 1.0.0, May 30, 2016

  • Ability to submit PageView events with JSON payload.
  • Support HttpURLConnection, OkHttp2 or OkHttp3 as transport layers.
  • Support org.json as JSON encoder.