Class – Tracker

Class

Tracker

public final class Tracker
extends java.lang.Object

Tracker entry point.

The Tracker is a Singleton that exposes functionality through public static methods. You do not create an instance of the Tracker. Instead, you configure it through the configure(Configuration) method.


Nested Class Summary

Modifier and Type Class and Description
static class  Tracker.Configuration
Tracker Configuration Object Builder.
static class Tracker.ConsentPartner
Intelligent Consent Management Partner Details.
static class  Tracker.Event
Event Object Builder for Standard and Custom Events.
static interface  Tracker.EventType
Tracker Event types.
static class  Tracker.IdentityLink
Identity Link Object Builder.
static interface  Tracker.LogLevel
Tracker Logging Levels.

Field Detail

Modifier and Type Field and Description
static int EVENT_TYPE_ACHIEVEMENT
public static final int EVENT_TYPE_ACHIEVEMENT

Achievement earned.

static int EVENT_TYPE_AD_VIEW
public static final int EVENT_TYPE_AD_VIEW

Ad View. Use for AD LTV.

static int EVENT_TYPE_ADD_TO_CART
public static final int EVENT_TYPE_ADD_TO_CART

Item added to cart.

static int EVENT_TYPE_ADD_TO_WISH_LIST
public static final int EVENT_TYPE_ADD_TO_WISH_LIST

Item added to wish list.

static int EVENT_TYPE_CHECKOUT_START
public static final int EVENT_TYPE_CHECKOUT_START

User started checking out.

static int EVENT_TYPE_CONSENT_GRANTED
Consent Granted.
static int EVENT_TYPE_LEVEL_COMPLETE
public static final int EVENT_TYPE_LEVEL_COMPLETE

User completed level.

static int EVENT_TYPE_PURCHASE
public static final int EVENT_TYPE_PURCHASE

Physical or in app purchase.

static int EVENT_TYPE_PUSH_OPENED
public static final int EVENT_TYPE_PUSH_OPENED

Push Opened.

static int EVENT_TYPE_RATING
public static final int EVENT_TYPE_RATING

User rating.

static int EVENT_TYPE_REGISTRATION_COMPLETE
public static final int EVENT_TYPE_REGISTRATION_COMPLETE

User completed registration.

static int EVENT_TYPE_SEARCH
public static final int EVENT_TYPE_SEARCH

User search.

static int EVENT_TYPE_TUTORIAL_COMPLETE
public static final int EVENT_TYPE_TUTORIAL_COMPLETE

User completed tutorial.

static int EVENT_TYPE_VIEW
public static final int EVENT_TYPE_VIEW

User viewed something.

static int LOG_LEVEL_DEBUG
public static final int LOG_LEVEL_DEBUG

Show diagnostic data.

static int LOG_LEVEL_ERROR
public static final int LOG_LEVEL_ERROR

Show only errors that halt continued operation.

static int LOG_LEVEL_INFO
public static final int LOG_LEVEL_INFO

Show status messages. (default).

static int LOG_LEVEL_NONE
public static final int LOG_LEVEL_NONE

Disable all logging.

static int LOG_LEVEL_TRACE
public static final int LOG_LEVEL_TRACE

Show additional diagnostic data. Corresponds to the Android Verbose log level.

static int LOG_LEVEL_WARN
public static final int LOG_LEVEL_WARN

Show warnings and errors that do not prevent continued operation.


Method Detail

Modifier and Type Method and Description
static void addPushToken

@AnyThread
public static void addPushToken(@NonNull java.lang.String token)

Adds a new Firebase Cloud Messaging instance ID token.

This should be called from the onTokenRefresh method within your FirebaseInstanceIdService.

Parameters:
token — Firebase Cloud Messaging Push Registration Token.

static void configure
@AnyThread
public static void configure(@NonNull Tracker.Configuration configuration)

Configures the Tracker.

The Tracker must be configured before it can be used.

Issues with an invalid configuration will be reported in the logcat during this configure call. To ensure the Tracker was properly configured you may call isConfigured().

NOTE: If you are doing an advanced configuration such as in a multiple process app then read the advanced usage section in Tracker.Configuration.

Parameters:
configuration — Tracker Configuration

static void ext
@AnyThread
public static void ext(@NonNull java.lang.String ext, @NonNull java.lang.String extDate)

Sets the version extension for the specific Tracker variant.

This must be performed prior to configure(Configuration) and should only be done by a wrapper SDK, never by the host app.

Parameters:
ext — See internal documentation for possible values.
extDate — See internal documentation for possible values.

static java.lang.String getAttribution
@Contract(pure=true)
@AnyThread
@NonNull
public static java.lang.String getAttribution()

Returns previously gathered attribution as serialized JSON.

Attribution information is usually available within about 10 seconds from the initial launch, although it is subject to a variety of conditions which can cause this time interval to be longer.

Server side attribution is handled automatically and is available from the Kochava Dashboard. Use this only if you need to use the attribution data within your app itself as it will otherwise cause needless network communication.

NOTE: In order to get attribution the Tracker must be configured with an attribution listener Tracker.Configuration.setAttributionListener(AttributionListener).

For a detailed explanation of attribution responses, refer to our Attribution Response Examples support documentation.

Returns:
Saved Attribution data as serialized JSON.

static java.lang.String getConsentDescription
@NonNull
public static java.lang.String getConsentDescription()

Returns the consent description.

If unavailable this will return an empty string.

Returns:
Consent description.

static java.lang.String getConsentPartners
@NonNull
public static Tracker.ConsentPartner[] getConsentPartners()

Returns the list of consent partners as configured on the Kochava dashboard.

If unavailable this will return an empty array.

Returns:
Array of consent partners.

static java.lang.String getConsentPartnersJson
@NonNull
public static java.lang.String getConsentPartnersJson()

Returns the list of consent partners as configured on the Kochava dashboard.

If unavailable this will return an empty JSON array.

Returns:
serialized JSON array of consent partners.

static java.lang.String getConsentResponseTime
public static long getConsentResponseTime()

Returns when consent was either granted or declined.

If consent is currently unknown either initially or after a previously granted consent was invalidated this will return 0.

Returns:
Unix timestamp (seconds) of the consent time or 0 if no consent set.

static java.lang.String getDeviceId
@AnyThread
@NonNull
public static java.lang.String getDeviceId()

Returns the generated unique Device ID.

This is available anytime the Tracker is configured.

NOTE: Different apps or users on the same device will have their own unique Device ID. Also an app reinstall will generate a new Device ID.

Returns:
The unique Device ID or an empty string if the Tracker has not been configured.

static InstallReferrer getInstallReferrer
@AnyThread
@NonNull
public static InstallReferrer getInstallReferrer()

Returns the app Install Referrer if present.

The install referrer is gathered during the first tracker configuration and should be available within a few seconds of app launch. On subsequent launches the result is cached and will be available any time the Tracker is configured.

If the install referrer has not yet been gathered an InstallReferrer object will be returned with status InstallReferrer.STATUS_NOT_GATHERED

Returns:
Install Referrer object.

static java.lang.String getVersion
@Contract(pure=true)
@AnyThread
@NonNull
public static java.lang.String getVersion()

Returns the Tracker version.

For native Android the format is “x.y.z”.

For wrapped Trackers (AIR, Unity, etc) the format is “x.y.z (WrapperName x.y.z)” where “WrapperName x.y.z” is the name and version of the wrapper.

Returns:
The Tracker Version.

static boolean isConfigured
@Contract(pure=true)
@AnyThread
public static boolean isConfigured()

Returns if the Tracker is currently configured. If called prior to Configure or if an error occurs during the configure(Configuration) call this will return false.

Once successfully configured this will remain true for the life of the app. Any attempts to configure the Tracker again will be ignored.

In some rare cases an internal Tracker error may cause it to shutdown and reset the configured state.

Returns:
True if the Tracker has been successfully configured. False otherwise.

static boolean isConsentGranted
public static boolean isConsentGranted()

Returns if consent is currently granted.

Consent is considered not granted until specifically granted by the user and set with setConsentGranted(boolean).

Previously granted consent may be invalidated at any time by an addition to the partner list or a change to the prompt ID. This will be indicated with a call to ConsentStatusChangeListener.onConsentStatusChange().

NOTE: Consent granted is only required if isConsentRequired() is true.

Returns:
True if consent is granted and False if unknown or declined.

static boolean isConsentGrantedOrNotRequired
public static boolean isConsentGrantedOrNotRequired()

Returns if consent is granted or consent is not required.

Returns:
True if either consent is granted or consent is not required.

static boolean IsConsentRequired
public static boolean isConsentRequired()

Returns if consent is currently required for this user.

Consent requirements are determined by a server handshake and are updated on a regular basis. Any time that required changes ConsentStatusChangeListener.onConsentStatusChange() will be called.

Prior to the first server handshake consent is considered to be required. The app should operate under that assumption until the callback indicates a change has occurred and consent may or may not actually be required.

Returns:
True if consent is required and False if not.

static boolean isConsentShouldPrompt
public static boolean isConsentShouldPrompt()

Returns if the host app should prompt the user for consent.

After prompting call clearConsentShouldPrompt() to clear the should prompt flag.

If the user then gives an explicit granted or declined response indicate it with setConsentGranted(boolean).

Returns:
True if the app should prompt the user for consent or False if they should not.

static boolean clearConsentShouldPrompt
public static void clearConsentShouldPrompt()

Clears the consent should prompt flag.

Call this to indicate the user is being prompted for consent.

This should be called when the prompt is shown to ensure the should prompt flag is cleared and the retry timer is started for the next prompt if they do not grant.

static boolean isSessionActive
@Contract(pure=true)
@AnyThread
public static boolean isSessionActive()

Returns if a session is currently active.

A session is defined as active if the Tracker is configured and there is a foreground Activity in at least the started state.

NOTE: Session tracking is only available when running on Android API 14+. Older devices will always return true if the Tracker is configured and false otherwise.

Returns:
True is session is active. False if not.

static boolean isSleep
@Contract(pure=true)
@AnyThread
public static boolean isSleep()

Returns if the Tracker is currently set to a sleep state or not.

Returns:
True if Tracker is in sleep state, False if normal operation.

static void removePushToken
@AnyThread
public static void removePushToken(@NonNull java.lang.String token)

Removes an existing Firebase Cloud Messaging instance ID token.

This should be called to disable Push Notification support.

Parameters:
token — Firebase Cloud Messaging Push Registration Token.

static void sendEvent
@AnyThread
public static void sendEvent(@NonNull Tracker.Event event)

Sends an Event.

Events may be batched to save on network traffic. Some level of delay prior to sending is normal.

Parameters:
event — Event instance.

static void sendEvent
public static void sendEvent(@NonNull java.lang.String eventName, @NonNull java.lang.String eventData)

Sends an event with a custom name and payload.

Event pre-registration is not required.

Event names may not be prepended with an underscore as that convention is reserved for Kochava events.

Events may be batched to save on network traffic. Some level of delay prior to sending is normal.

Parameters:
eventName — Event Name. Must be NonNull with a length >= 1.
eventData — Event Data (typically single-level serialized json). Must be NonNull.

static void sendEventDeepLink
@AnyThread
public static void sendEventDeepLink(@NonNull java.lang.String deepLink)

Send a deep link event.

Events may be batched to save on network traffic. Some level of delay prior to sending is normal.

Parameters:
deepLink — Url encoded string.

static void setAppLimitAdTracking
@AnyThread
public static void setAppLimitAdTracking(boolean appLimitAdTracking)

Sets if app level advertising tracking should be limited.

This value is unrelated to and is sent in addition to the operating system limit ad tracking value.

Default is False.

Parameters:
appLimitAdTracking — True to limit ad tracking for this app. False for normal operation.

static void setConsentGranted
public static void setConsentGranted(boolean isGranted)

Sets the user’s response to the consent prompt.

Sets the response from the user if they specifically granted or declined consent. If they dismiss the dialog or otherwise do not answer then do not call this method.

See clearConsentShouldPrompt() to indicate that the user was shown the consent prompt.

If consent is not required then you should not prompt the user or call this method.

Parameters:
isGranted — True if the user granted consent or False if they declined consent.

static void setDeepLinkListener
public static void setDeepLinkListener(@Nullable
android.net.Uri uri,
@NonNull
DeepLinkListener deepLinkListener)

Sets the deep link parameter listener.

The first time a deep link is requested the install referrer based deferred deep link will be available if present. All subsequent calls will only consider the launch intent uri.

Uses the default 4 second timeout for the deferred deep link to be available.

Parameters:
uri — Launch intent data uri (can be null).
deepLinkListener — Completion listener.

static void setDeepLinkListener
public static void setDeepLinkListener(@Nullable
android.net.Uri uri,
int timeout,
@NonNull
DeepLinkListener deepLinkListener)

Sets the deep link parameter listener.

The first time a deep link is requested the install referrer based deferred deep link will be available if present. All subsequent calls will only consider the launch intent uri.

Parameters:
uri — Launch intent data uri (can be null).
timeout — Maximum amount of time in milliseconds to wait for a deferred deep link. Range is 250 -> 10,000.
deepLinkListener — Completion listener.

static void setIdentityLink
@AnyThread
public static void setIdentityLink(@NonNull Tracker.IdentityLink identityLink)

Sets a user identity link that is used for linking based off of external criteria such as a user login.

Parameters:
identityLink — IdentityLink that maps key names with values.

static void setSleep
@AnyThread
public static void setSleep(boolean sleep)

Sets the Tracker sleep state.

Sleep mode ON — Prevents the Tracker from sending any network requests. It will still process all incoming events and sessions. Any queued items will be sent as soon as sleep mode is disabled. Sleep mode state is not preserved across launches.

This should only be used if there is some additional information needed before the Tracker continues such as an identity link, runtime permission, waiting on user to accept privacy policy, or other.

USE CASE: Your app is using email attribution and is running on an Android device with Runtime Permissions. Start the Tracker in Application.onCreate, set sleep==true and in the onRequestPermissionsResult method for your GET_ACCOUNTS permission set sleep==false to continue Tracker initialization.

NOTE: sleep mode will not turn off on its own. If you enable it you must also ensure you disable it.

Parameters:
sleep — True to enable sleep, False to disable sleep and resume normal operation.


See Also

Event Type Tracker.Event

Event Object Builder for Standard and Custom Events.

Log Level Tracker.Configuration.setLogLevel(int)

Constant Field Values

 
 

Last Modified: Jun 20, 2018 at 11:30 am