Migration Guide

A migration guide for users of the KochavaTracker Android SDK, to help understand the changes and make the transition to newer versions. This guide only describes changes that require a manual migration. For more details on new features and the full integration instructions see the Getting Started Guide.

When performing the migration start with the oldest section that is applicable to your current SDK version and complete that migration before performing the more recent migration steps.

Migration 3.0.0 to 3.3.0

Install Referrer:

Version 3.3.0 adds support for the new Google Install Referrer API. This API is used internally by the SDK and requires the addition of a dependency. Add the following to your module level build.gradle file alongside the Kochava SDK.

New –

1

compile'com.android.installreferrer:installreferrer:1.0'

Attribution Listener:

The Tracker now supports updating attribution on subsequent launches and calling the attribution listener methods again. Since this is a behavior breaking change a new listener with this functionality has been provided and the old one deprecated. Migrate to the revised AttributionUpdateListener and ensure your logic can handle being called on future launches.

Old –

1

2

3

4

5

6

7

8

9

Tracker.configure(newConfiguration(getApplicationContext())

.setAppGuid("_YOUR_APP_GUID_")

.setAttributionListener(newAttributionListener(){

@Override

publicvoidonAttributionReceived(@NonNull Stringattribution){

}

})

);

New –

1

2

3

4

5

6

7

8

9

Tracker.configure(newConfiguration(getApplicationContext())

.setAppGuid("_YOUR_APP_GUID_")

.setAttributionUpdateListener(newAttributionUpdateListener(){

@Override

publicvoidonAttributionUpdated(@NonNull Stringattribution){

}

})

);

Broadcast Receiver:

The broadcast receiver is now automatically included in the AAR. Remove the following entry from your manifest.

Old –

1

2

3

4

5

6

<receiver android:name="com.kochava.base.ReferralReceiver"

android:exported="true">

<intent-filter>

<action android:name="com.android.vending.INSTALL_REFERRER"/>

</intent-filter>

</receiver>

New –

Automatic from the AAR.

Migration to 3.0.0

Version 3.0.0 is a comprehensive rewrite of the Kochava Android SDK. The package name, include method, and entire public API has been changed.

Including the Library:

The KochavaTracker library has changed from being a direct download of a JAR file to either a direct download of an AAR or import of the AAR via Maven.

It is recommended that you follow the Getting Started Guide to include the new KochavaTracker library before moving on with this guide.

Import:

The main entry point to the sdk was changed. All primary components are based out of the new Tracker class using nested classes, static methods, and static variables.

Old –

1

2

3

4

5

6

7

8

//Primary Entry Point

import com.kochava.android.tracker.Feature;

//Initialization and Configuration

import com.kochava.android.tracker.Feature.INPUTITEMS;

//Events

import com.kochava.android.tracker.EventParameters;

//Attribution Response Listener

import android.os.Handler;

New –

1

2

3

4

5

6

7

8

9

10

//Primary Entry Point

import com.kochava.base.Tracker;

//Initialization and Configuration

import com.kochava.base.Tracker.Configuration;

//Events

import com.kochava.base.Tracker.Event;

//Attribution Response Listener

import com.kochava.base.AttributionListener;

//Identity Link

import com.kochava.base.Tracker.IdentityLink;

Broadcast Receiver:

The package name and class name of the broadcast receiver that listens for the INSTALL_REFERRER has changed. You must remove the old broadcast receiver from your manifest and include the new one.

Old –

1

2

3

4

5

6

<receiver android:name="com.kochava.android.tracker.ReferralCapture

android:exported="true">

<intent-filter>

<action android:name="com.android.vending.INSTALL_REFERRER"/>

</intent-filter>

</receiver>

New –

1

2

3

4

5

6

<receiver android:name="com.kochava.base.ReferralReceiver"

android:exported="true">

<intent-filter>

<action android:name="com.android.vending.INSTALL_REFERRER"/>

</intent-filter>

</receiver>

Tracker Initialization:

The basic approach to initialize the tracker was replaced. The free form hashmap input has been replaced with a fluent interface for all input parameters. All inputs are now set in the configuration object prior to passing it to the Tracker.

Logging has changed from the all or nothing on/off approach to a log level. This log level closely aligns with the Android log levels. Options include NONE, ERROR, WARN, INFO, DEBUG, and TRACE (Verbose). The default level is INFO.

Old –

1

2

3

4

HashMap<String,Object>datamap=newHashMap<>();

datamap.put(INPUTITEMS.KOCHAVA_APP_ID,"_YOUR_APP_GUID_");

datamap.put(INPUTITEMS.DEBUG_ON,true);

Feature tracker=newFeature(getApplicationContext(),datamap);

New –

1

2

3

4

Tracker.configure(newConfiguration(getApplicationContext())

.setAppGuid("_YOUR_APP_GUID_")

.setLogLevel(Tracker.LOG_LEVEL_INFO)

);

Attribution Listener:

The attribution listener has changed to an interface implementation instead of a handler. This method will be called on the main thread.

The new attribution listener is now passed through the Configuration object instead of with a static setter. The format of the attribution string has changed. See Public Methods below for more info.

Passing an explicit “Request Attribution” boolean is no longer required. Passing in an implementation of the AttributionListener interface implies it.

Old –

1

2

3

4

5

6

7

8

9

10

11

12

13

14

Handler attributionResponseListener=newHandler(){

@Override

publicvoidhandleMessage(Message msg){

Stringattribution=msg.getData().getString(Feature.ATTRIBUTION_DATA);

}

};

Feature.setAttributionHandler(attributionResponseListener);

HashMap<String,Object>datamap=newHashMap<>();

datamap.put(INPUTITEMS.KOCHAVA_APP_ID,"_YOUR_APP_GUID_");

datamap.put(INPUTITEMS.REQUEST_ATTRIBUTION,true);

Feature tracker=newFeature(getApplicationContext(),datamap);

New –

1

2

3

4

5

6

7

8

9

Tracker.configure(newConfiguration(getApplicationContext())

.setAppGuid("_YOUR_APP_GUID_")

.setAttributionListener(newAttributionListener(){

@Override

publicvoidonAttributionReceived(@NonNull Stringattribution){

}

})

);

Public Methods:

The getter methods are fairly similar but are now static instead of instance methods.
The format of the response of getAttribution has changed. An organic install will now return serialized json of “{“attribution”;”false”}” instead of the string “false”. View the reference for full details.

Old –

1

2

3

4

5

6

7

8

//Retrieve saved attribution json

Stringattribution=Feature.getAttributionData();

//Retrieve the generated device id

StringdeviceId=Feature.getKochavaDeviceId();

//App limit ad tracking property

tracker.setAppLimitTracking(true);

New –

1

2

3

4

5

6

7

8

//Retrieve saved attribution json

Stringattribution=Tracker.getAttribution();

//Retrieve the generated device id

StringdeviceId=Tracker.getDeviceId();

//App limit ad tracking property

Tracker.setAppLimitAdTracking(true);

Identity Link:

Identity Link has been changed from a HashMap to a custom IdentityLink object with a fluent interface. To aid with migration the new IdentityLink object can also have the old HashMap added to it.

Old –

1

2

3

4

5

6

7

8

9

10

11

12

13

14

//At Configuration

HashMap<String,Object>datamap=newHashMap<>();

datamap.put(INPUTITEMS.KOCHAVA_APP_ID,"_YOUR_APP_GUID_");

HashMap<String,String>identityLink=newHashMap<>();

identityLink.put("identity_key","aaaa-bbbb-cccc-dddd");

datamap.put(INPUTITEMS.IDENTITY_LINK,identityLink);

Feature tracker=newFeature(getApplicationContext(),datamap);

//Post Configuration

HashMap<String,String>identityLink=newHashMap<>();

identityLink.put("identity_key","aaaa-bbbb-cccc-dddd");

tracker.linkIdentity(identityLink);

New –

1

2

3

4

5

6

7

8

9

10

11

12

//At Configuration

Tracker.configure(newConfiguration(getApplicationContext())

.setAppGuid("_YOUR_APP_GUID_")

.setIdentityLink(newIdentityLink()

.add("identity_key","aaaa-bbbb-cccc-dddd")

)

);

//Post Configuration

Tracker.setIdentityLink(newIdentityLink()

.add("identity_key","aaaa-bbbb-cccc-dddd")

);

Standard Events:

EventParameters has been renamed to Event and now uses a fluent interface. Custom parameters and names are now supported through this Event class.