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 –
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 –
Tracker.configure(new Configuration(getApplicationContext())
.setAppGuid("_YOUR_APP_GUID_")
.setAttributionListener(new AttributionListener() {
@Override
public void onAttributionReceived(@NonNull String attribution) {
}
})
);
New –
Tracker.configure(new Configuration(getApplicationContext())
.setAppGuid("_YOUR_APP_GUID_")
.setAttributionUpdateListener(new AttributionUpdateListener() {
@Override
public void onAttributionUpdated(@NonNull String attribution) {
}
})
);
Broadcast Receiver:
The broadcast receiver is now automatically included in the AAR. Remove the following entry from your manifest.
Old –
<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 –
//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 –
//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 –
<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 –
<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 –
HashMap<String, Object> datamap = new HashMap<>();
datamap.put(INPUTITEMS.KOCHAVA_APP_ID, "_YOUR_APP_GUID_");
datamap.put(INPUTITEMS.DEBUG_ON, true);
Feature tracker = new Feature(getApplicationContext(), datamap);
New –
Tracker.configure(new Configuration(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 –
Handler attributionResponseListener = new Handler() {
@Override
public void handleMessage(Message msg) {
String attribution = msg.getData().getString(Feature.ATTRIBUTION_DATA);
}
};
Feature.setAttributionHandler(attributionResponseListener);
HashMap<String, Object> datamap = new HashMap<>();
datamap.put(INPUTITEMS.KOCHAVA_APP_ID, "_YOUR_APP_GUID_");
datamap.put(INPUTITEMS.REQUEST_ATTRIBUTION, true);
Feature tracker = new Feature(getApplicationContext(), datamap);
New –
Tracker.configure(new Configuration(getApplicationContext())
.setAppGuid("_YOUR_APP_GUID_")
.setAttributionListener(new AttributionListener() {
@Override
public void onAttributionReceived(@NonNull String attribution) {
}
})
);
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 –
//Retrieve saved attribution json
String attribution = Feature.getAttributionData();
//Retrieve the generated device id
String deviceId = Feature.getKochavaDeviceId();
//App limit ad tracking property
tracker.setAppLimitTracking(true);
New –
//Retrieve saved attribution json
String attribution = Tracker.getAttribution();
//Retrieve the generated device id
String deviceId = 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 –
//At Configuration
HashMap<String, Object> datamap = new HashMap<>();
datamap.put(INPUTITEMS.KOCHAVA_APP_ID, "_YOUR_APP_GUID_");
HashMap<String, String> identityLink = new HashMap<>();
identityLink.put("identity_key", "aaaa-bbbb-cccc-dddd");
datamap.put(INPUTITEMS.IDENTITY_LINK, identityLink);
Feature tracker = new Feature(getApplicationContext(), datamap);
//Post Configuration
HashMap<String, String> identityLink = new HashMap<>();
identityLink.put("identity_key", "aaaa-bbbb-cccc-dddd");
tracker.linkIdentity(identityLink);
New –
//At Configuration
Tracker.configure(new Configuration(getApplicationContext())
.setAppGuid("_YOUR_APP_GUID_")
.setIdentityLink(new IdentityLink()
.add("identity_key", "aaaa-bbbb-cccc-dddd")
)
);
//Post Configuration
Tracker.setIdentityLink(new IdentityLink()
.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.
Old –
EventParameters eventParameters = new EventParameters(EventType.Achievement);
eventParameters.name("event name");
eventParameters.duration(123);
tracker.eventStandard(eventParameters);
New –
Tracker.sendEvent(new Event(Tracker.EVENT_TYPE_ACHIEVEMENT)
.setName("name")
.setDuration(123)
);
Other Events:
All event methods now start with “sendEvent” for their names and have had parameters simplified where possible.
Old –
//Custom Event
tracker.event("custom name", "custom data");
//Deep Link Event
tracker.deepLinkEvent("http://mydeeplink.com");
//Google Play IAP Receipt
HashMap<String, String> receipt = new HashMap<>();
receipt.put("purchaseData", "receipt json");
receipt.put("dataSignature", "receipt json signature");
tracker.eventWithReceipt("receipt name", "receipt data", receipt);
New –
//Custom Event
Tracker.sendEvent("custom name", "custom data");
//Deep Link Event
Tracker.sendEventDeepLink("http://mydeeplink.com");
//Google Play IAP Receipt is now handled through the Event class.
Tracker.sendEvent(new Event(Tracker.EVENT_TYPE_PURCHASE)
.setGooglePlayReceipt("dataJson", "dataSignature")
);
Removed Methods:
Some methods have been removed and some additional methods and functionality have been added. See the integration documentation for more details.
//It is no longer possible to change the log level after the Tracker has been configured.
Feature.enableDebug(true);
Feature.setErrorDebug(true);
//The new Tracker has improved functionality for handling sending events to the server.
//The override to force a flush has been removed.
Feature.flush();
//The new Tracker has rewritten session tracking and no longer supports overrides.
tracker.startSession();
tracker.endSession();
