public final class Tracker
extends java.lang.Object
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.
| Modifier and Type | Class and Description |
|---|---|
static class |
Tracker.Configuration
Tracker Configuration Builder.
|
static class |
Tracker.ConsentPartner
Intelligent Consent Management Partner Details.
|
static class |
Tracker.Event
Event Builder for Standard and Custom Events.
|
static interface |
Tracker.EventType
Tracker Event types.
|
static class |
Tracker.IdentityLink
Identity Link Builder.
|
static interface |
Tracker.LogLevel
Tracker Logging Levels.
|
| Modifier and Type | Field and Description |
|---|---|
static int |
EVENT_TYPE_ACHIEVEMENT
Achievement earned.
|
static int |
EVENT_TYPE_AD_CLICK
Ad Click
|
static int |
EVENT_TYPE_AD_VIEW
Ad View.
|
static int |
EVENT_TYPE_ADD_TO_CART
Item added to cart.
|
static int |
EVENT_TYPE_ADD_TO_WISH_LIST
Item added to wish list.
|
static int |
EVENT_TYPE_CHECKOUT_START
User started checking out.
|
static int |
EVENT_TYPE_CONSENT_GRANTED
Consent Granted.
|
static int |
EVENT_TYPE_DEEP_LINK
Deep Link
|
static int |
EVENT_TYPE_LEVEL_COMPLETE
User completed level.
|
static int |
EVENT_TYPE_PURCHASE
Physical or in app purchase.
|
static int |
EVENT_TYPE_PUSH_OPENED
Push Opened.
|
static int |
EVENT_TYPE_PUSH_RECEIVED
Push Received.
|
static int |
EVENT_TYPE_RATING
User rating.
|
static int |
EVENT_TYPE_REGISTRATION_COMPLETE
User completed registration.
|
static int |
EVENT_TYPE_SEARCH
User search.
|
static int |
EVENT_TYPE_START_TRIAL
Start Trial
|
static int |
EVENT_TYPE_SUBSCRIBE
Subscribe
|
static int |
EVENT_TYPE_TUTORIAL_COMPLETE
User completed tutorial.
|
static int |
EVENT_TYPE_VIEW
User viewed something.
|
static int |
LOG_LEVEL_DEBUG
Show diagnostic data.
|
static int |
LOG_LEVEL_ERROR
Show only errors that halt continued operation.
|
static int |
LOG_LEVEL_INFO
Show status messages.
|
static int |
LOG_LEVEL_NONE
Disable all logging.
|
static int |
LOG_LEVEL_TRACE
Show verbose diagnostic data.
|
static int |
LOG_LEVEL_WARN
Show warnings and errors that do not prevent continued operation.
|
| Modifier and Type | Method and Description |
|---|---|
static void |
addPushToken(java.lang.String token)
Adds a new Firebase Cloud Messaging instance ID token.
|
static void |
clearConsentShouldPrompt()
Clears the consent should prompt flag.
|
static void |
configure(Tracker.Configuration configuration)
Configures the Tracker.
|
static void |
executeAdvancedInstruction(java.lang.String key,
java.lang.String value)
Use only if directed to by your Client Success Manager.
|
static java.lang.String |
getAttribution()
Returns previously gathered attribution as serialized json.
|
static java.lang.String |
getConsentDescription()
Returns the consent description.
|
static Tracker.ConsentPartner[] |
getConsentPartners()
Returns the list of consent partners as configured on the Kochava dashboard.
|
static java.lang.String |
getConsentPartnersJson()
Returns the list of consent partners as configured on the Kochava dashboard.
|
static long |
getConsentResponseTime()
Returns when consent was either granted or declined.
|
static java.lang.String |
getDeviceId()
Returns the generated unique Device ID.
|
static InstallReferrer |
getInstallReferrer()
Returns the app Install Referrer if present.
|
static java.lang.String |
getVersion()
Returns the Tracker version.
|
static boolean |
isConfigured()
Returns if the Tracker is currently configured.
|
static boolean |
isConsentGranted()
Returns if consent is currently granted.
|
static boolean |
isConsentGrantedOrNotRequired()
Returns if consent is granted or consent is not required.
|
static boolean |
isConsentRequired()
Returns if consent is currently required for this user.
|
static boolean |
isConsentRequirementsKnown()
Returns if the SDK has completed a handshake with the server and determined if consent is required
and if so what the partners are and if the app should prompt the user.
|
static boolean |
isConsentShouldPrompt()
Returns if the host app should prompt the user for consent.
|
static boolean |
isSessionActive()
Returns if a session is currently active.
|
static boolean |
isSleep()
Returns if the Tracker is currently set to a sleep state or not.
|
static void |
processDeeplink(java.lang.String deeplinkData,
DeeplinkProcessedListener deeplinkProcessedListener)
Process a launch deeplink from your activity.onStart method using the default 10 second timeout.
|
static void |
processDeeplink(java.lang.String deeplinkData,
double timeout,
DeeplinkProcessedListener deeplinkProcessedListener)
Process a launch deeplink from your activity.onStart method.
|
static void |
removePushToken(java.lang.String token)
Removes an existing Firebase Cloud Messaging instance ID token.
|
static void |
sendEvent(java.lang.String eventName,
java.lang.String eventData)
Sends an event with a custom name and payload.
|
static void |
sendEvent(Tracker.Event event)
Sends an Event.
|
static void |
sendEventDeepLink(java.lang.String deepLink)
Deprecated.
As of 3.4.1, because deep link functionality has been added to Tracker.Event.
|
static void |
setAppLimitAdTracking(boolean appLimitAdTracking)
Sets if app level advertising tracking should be limited.
|
static void |
setConsentGranted(boolean isGranted)
Sets the user's response to the consent prompt.
|
static void |
setConsentRequired(boolean required)
Sets if consent is required for the current user.
|
static void |
setDeepLinkListener(android.net.Uri uri,
DeepLinkListener deepLinkListener)
Sets the deeplink parameter listener.
|
static void |
setDeepLinkListener(android.net.Uri uri,
int timeout,
DeepLinkListener deepLinkListener)
Sets the deeplink parameter listener.
|
static void |
setIdentityLink(Tracker.IdentityLink identityLink)
Sets a user identity link that is used for linking based off of external criteria such as a user login.
|
static void |
setSleep(boolean sleep)
Sets the Tracker sleep state.
|
static void |
unConfigure(boolean clearPersistedData)
UnConfigures the Tracker and optionally removes SDK persisted data.
|
public static final int LOG_LEVEL_NONE
public static final int LOG_LEVEL_ERROR
public static final int LOG_LEVEL_WARN
public static final int LOG_LEVEL_INFO
public static final int LOG_LEVEL_DEBUG
public static final int LOG_LEVEL_TRACE
public static final int EVENT_TYPE_ACHIEVEMENT
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_ADD_TO_CART
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_ADD_TO_WISH_LIST
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_CHECKOUT_START
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_LEVEL_COMPLETE
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_PURCHASE
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_RATING
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_REGISTRATION_COMPLETE
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_SEARCH
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_TUTORIAL_COMPLETE
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_VIEW
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_AD_VIEW
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_PUSH_RECEIVED
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_PUSH_OPENED
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_CONSENT_GRANTED
Note: When using this event type with Intelligent Consent Management the consent prompt ID and response time are automatically added to the event under the keys "content_id" and "date".
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_DEEP_LINK
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_AD_CLICK
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_START_TRIAL
Tracker.Event,
Constant Field Valuespublic static final int EVENT_TYPE_SUBSCRIBE
Tracker.Event,
Constant Field Valuespublic static void configure(Tracker.Configuration configuration)
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.
configuration - Tracker Configurationpublic static boolean isConfigured()
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.
public static void unConfigure(boolean clearPersistedData)
This method allows you to stop the Tracker should you wish to after having already configured it on this app launch. This should be used at most one time per app run. Multiple reconfigurations on a single app launch are not supported.
WARNING: This will stop the Tracker and may clear all data. Clearing data will cause any new configuration of the Tracker to look like a new install.
clearPersistedData - True to clear SDK data. False to maintain data persistence.public static boolean isSessionActive()
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.
public static boolean isSleep()
setSleep(boolean)public static void setSleep(boolean sleep)
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.
Example: 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.
sleep - True to enable sleep, False to disable sleep and resume normal operation.isSleep(),
Tracker.Configuration.setSleep(boolean)public static java.lang.String getVersion()
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.
public static java.lang.String getAttribution()
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.setAttributionUpdateListener(AttributionUpdateListener).
For a detailed explanation of attribution responses, refer to our Attribution Response Examples support documentation.
AttributionUpdateListenerpublic static java.lang.String getDeviceId()
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.
public static InstallReferrer getInstallReferrer()
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
public static void addPushToken(java.lang.String token)
This should be called from the onTokenRefresh method within your FirebaseInstanceIdService.
public void onTokenRefresh() {
Tracker.setPushToken(FirebaseInstanceId.getInstance().getToken());
}
token - Firebase Cloud Messaging Push Registration Token.public static void removePushToken(java.lang.String token)
This should be called to disable Push Notification support.
Tracker.removePushToken(FirebaseInstanceId.getInstance().getToken());
token - Firebase Cloud Messaging Push Registration Token.public static void setAppLimitAdTracking(boolean appLimitAdTracking)
This value is unrelated to and is sent in addition to the operating system limit ad tracking value.
Default is False.
appLimitAdTracking - True to limit ad tracking for this app. False for normal operation.Tracker.Configuration.setAppLimitAdTracking(boolean)public static void setIdentityLink(Tracker.IdentityLink identityLink)
identityLink - IdentityLink that maps key names with values.setIdentityLink(IdentityLink)@Deprecated public static void sendEventDeepLink(java.lang.String deepLink)
Events may be batched to save on network traffic. Some level of delay prior to sending is normal.
deepLink - Url encoded string.public static void sendEvent(Tracker.Event event)
Events may be batched to save on network traffic. Some level of delay prior to sending is normal.
event - Event instance.Tracker.Event,
Post-Install Event Examplespublic static void sendEvent(java.lang.String eventName,
java.lang.String eventData)
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.
eventName - Event Name. Must be NonNull with a length >= 1.eventData - Event Data (typically single-level serialized json). Must be NonNull.public static void setDeepLinkListener(android.net.Uri uri,
DeepLinkListener deepLinkListener)
The first time a deeplink is requested the install referrer based deferred deeplink will be available if present. All subsequent calls will only consider the launch intent uri.
Uses the default 4 second timeout for the deferred deeplink to be available.
uri - Launch intent data uri (can be null).deepLinkListener - Completion listener.public static void setDeepLinkListener(android.net.Uri uri,
int timeout,
DeepLinkListener deepLinkListener)
The first time a deeplink is requested the install referrer based deferred deeplink will be available if present. All subsequent calls will only consider the launch intent uri.
uri - Launch intent data uri (can be null).timeout - Maximum amount of time in milliseconds to wait for a deferred deeplink. Range is 250 -> 10,000.deepLinkListener - Completion listener.public static boolean isConsentRequirementsKnown()
Once true it will remain true on all subsequent launches.
If consent is in manual managed mode this will always return true.
public static java.lang.String getConsentDescription()
If unavailable this will return an empty string.
Tracker.Configuration.setIntelligentConsentManagement(boolean)public static boolean isConsentGrantedOrNotRequired()
public static boolean isConsentRequired()
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.
If consent is in manual managed mode this will default to true and update only based on what the app sets with setConsentRequired(boolean).
Tracker.Configuration.setIntelligentConsentManagement(boolean),
ConsentStatusChangeListenerpublic static void setConsentRequired(boolean required)
This method is only available if consent is in manual managed mode. See Tracker.Configuration.setManualManagedConsentRequirements(boolean).
Consent defaults to being required until otherwise specified.
required - True if consent is required for this user and false if not.public static boolean isConsentGranted()
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.
Tracker.Configuration.setIntelligentConsentManagement(boolean),
ConsentStatusChangeListenerpublic static void setConsentGranted(boolean isGranted)
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.
isGranted - True if the user granted consent or False if they declined consent.Tracker.Configuration.setIntelligentConsentManagement(boolean),
ConsentStatusChangeListenerpublic static long getConsentResponseTime()
If consent is currently unknown either initially or after a previously granted consent was invalidated this will return 0.
Tracker.Configuration.setIntelligentConsentManagement(boolean),
ConsentStatusChangeListenerpublic static boolean isConsentShouldPrompt()
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).
Tracker.Configuration.setIntelligentConsentManagement(boolean),
ConsentStatusChangeListenerpublic static void clearConsentShouldPrompt()
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.
public static java.lang.String getConsentPartnersJson()
If unavailable this will return an empty json array.
Tracker.Configuration.setIntelligentConsentManagement(boolean),
ConsentStatusChangeListenerpublic static Tracker.ConsentPartner[] getConsentPartners()
If unavailable this will return an empty array.
Tracker.Configuration.setIntelligentConsentManagement(boolean),
ConsentStatusChangeListenerpublic static void processDeeplink(java.lang.String deeplinkData,
DeeplinkProcessedListener deeplinkProcessedListener)
Uses default of 10 second timeout.
deeplinkData - string obtained from intent.getDataString()deeplinkProcessedListener - result callback handler.public static void processDeeplink(java.lang.String deeplinkData,
double timeout,
DeeplinkProcessedListener deeplinkProcessedListener)
deeplinkData - string obtained from intent.getDataString()timeout - in seconds.deeplinkProcessedListener - result callback handler.public static void executeAdvancedInstruction(java.lang.String key,
java.lang.String value)
key - command.value - argument.