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.
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 topspin@npo.nl
Add the Topspin library as a dependency of your application:
repositories {
maven {
url "https://packagecloud.io/priv/<PACKAGECOULD_READ_TOKEN>/npo-data/android-tagging-sdk/maven2"
}
// If you use the AT Internet backend
maven {
url "https://dl.bintray.com/atinternet/maven/"
}
}
dependencies {
compile 'nl.npo.topspin:topspin-android:<latest-version>'
// If you use AT Internet, check github SDK repo for compatible version
// https://github.com/npo-topspin/topspin-tag-android/blob/master/library/build.gradle
implementation 'com.atinternet:Tracker:<version-from-github-here>'
}
Make sure the following permissions are requested in your manifest file:
android.permission.INTERNETandroid.permission.ACCESS_NETWORK_STATE (if you use AT Internet)Initialize Topspin library in your Application subclass.
public class TestApp extends Application {
@Override
public void onCreate() {
super.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)
.build(),
new AtInternetPlugin.Builder(Omgeving.DEV)
.build())
).build();
// 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
TopspinInstance.init(topspin);
// Register app to automatically send
// app-lifecycle events
topspin.registerAppLifecycle(this);
}
}
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;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// page view, inheriting global labels from app
mTracker = TopspinInstance.get().createTracker();
// set required labels for a page
mTracker.getPageLabels()
.niveau1("start")
.pagina("home");
// perform actual pageview
mTracker.contentView()
// optional: referrer
.setReferrer("homescreen")
.send();
}
}
To record more events from the same page, re-use the Tracker:
public void onButtonClicked() {
mTracker.customEvent("buttonClicked", CustomEventType.Action)
.send();
}
For recording stream events, create a StreamTracker from the tracker:
public void startPlayback() {
mStreamRecorder = mTracker.stream("KNO_2308383");
mStreamRecorder.load();
mVideoView.setVideoPath(mVideoUrl);
// when the video stars:
// mStreamRecorder.start(0);
}
public void pause() {
mStreamRecorder.pause(mVideoView.getCurrentPosition());
mVideoView.pause();
}
A real-world player would add various callbacks to the player which call the corresponding methods on the StreamRecorder.
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.
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.
No changes required, version 1.6.0 can just be replaced with this one.
android.permission.ACCESS_NETWORK_STATE to the app’s manifest.Add code to the app-wide Topspin initialisation code:
topspin.registerAppLifecycle(this);
Use Tracker.editorials(), Tracker.search() and Tracker.push() to create trackers for editorials, search queries and push messages
Use StreamTracker.streamExternal() when playback switches to an external playback device, like Chromecast.
nmoPanelId property on Topspin.application/json Content-Type
to come without the encoding parameter.