com.amplitude.api

Class AmplitudeClient

java.lang.Object

com.amplitude.api.AmplitudeClient

Direct Known Subclasses:

PinnedAmplitudeClient

public class AmplitudeClient
extends java.lang.Object

AmplitudeClient

This is the SDK instance class that contains all of the SDK functionality.

Note: call the methods on the default shared instance in the Amplitude class, for example: Amplitude.getInstance().logEvent();

Many of the SDK functions return the SDK instance back, allowing you to chain multiple method calls together, for example: Amplitude.getInstance().initialize(this, "APIKEY").enableForegroundTracking(getApplication())

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	apiKey The Amplitude App API key.
protected Call.Factory	callFactory The shared OkHTTPClient instance.
protected android.content.Context	context The Android App Context.
protected com.amplitude.api.DatabaseHelper	dbHelper The shared Amplitude database helper instance.
static java.lang.String	DEVICE_ID_KEY The pref/database key for the device ID value.
protected java.lang.String	deviceId The user's Device ID value.
protected DeviceInfo	deviceInfo
static java.lang.String	END_SESSION_EVENT The event type for end session events.
protected boolean	initialized
protected java.lang.String	instanceName The name for this instance of AmplitudeClient.
static java.lang.String	LAST_EVENT_ID_KEY The pref/database key for the last event ID value.
static java.lang.String	LAST_EVENT_TIME_KEY The pref/database key for the last event time.
static java.lang.String	LAST_IDENTIFY_ID_KEY The pref/database key for the last identify ID value.
static java.lang.String	OPT_OUT_KEY The pref/database key for the opt out flag.
protected java.lang.String	platform The device's Platform value.
static java.lang.String	PREVIOUS_SESSION_ID_KEY The pref/database key for the previous session ID value.
static java.lang.String	SEQUENCE_NUMBER_KEY The pref/database key for the sequence number.
static java.lang.String	START_SESSION_EVENT The event type for start session events.
static java.lang.String	USER_ID_KEY The pref/database key for the user ID value.
protected java.lang.String	userId The user's ID value.

Constructor Summary

Constructors

Constructor and Description
AmplitudeClient() Instantiates a new default instance AmplitudeClient and starts worker threads.
AmplitudeClient(java.lang.String instance) Instantiates a new AmplitudeClient with instance name and starts worker threads.

Method Summary

Modifier and Type	Method and Description
void	addEventMiddleware(Middleware middleware) Add middleware to the middleware runner
protected java.lang.String	bytesToHexString(byte[] bytes) Internal method to convert bytes to hex string
void	clearUserProperties() Clear user properties.
protected boolean	contextAndApiKeySet(java.lang.String methodName) Internal method to check whether application context and api key are set
AmplitudeClient	disableCoppaControl() Disable COPPA (Children's Online Privacy Protection Act) restrictions on ADID, city, IP address and location tracking.
AmplitudeClient	disableDiagnosticLogging() Deprecated. - We removed Diagnostics class and this function has no-op. Will completely remove it in the near future.
AmplitudeClient	disableLocationListening() Disable location listening in the SDK.
AmplitudeClient	enableCoppaControl() Enable COPPA (Children's Online Privacy Protection Act) restrictions on ADID, city, IP address and location tracking.
AmplitudeClient	enableDiagnosticLogging() Deprecated. - We removed Diagnostics class and this function has no-op. Will completely remove it in the near future.
AmplitudeClient	enableForegroundTracking(android.app.Application app) Enable foreground tracking for the SDK.
AmplitudeClient	enableLocationListening() Enable location listening in the SDK.
AmplitudeClient	enableLogging(boolean enableLogging) Enable/disable message logging by the SDK.
AmplitudeClient	enableNewDeviceIdPerInstall(boolean newDeviceIdPerInstall) Deprecated.
protected long	getCurrentTimeMillis() Internal method to fetch the current time millis.
java.lang.String	getDeviceId() Get the current device id.
AmplitudeServerZone	getServerZone() Get Amplitude Server Zone
long	getSessionId() Gets the current session id.
java.lang.String	getUserId() Gets the user's id.
void	groupIdentify(java.lang.String groupType, java.lang.Object groupName, Identify groupIdentify)
void	groupIdentify(java.lang.String groupType, java.lang.Object groupName, Identify groupIdentify, boolean outOfSession)
void	groupIdentify(java.lang.String groupType, java.lang.Object groupName, Identify groupIdentify, boolean outOfSession, MiddlewareExtra extra)
void	groupIdentify(java.lang.String groupType, java.lang.Object groupName, org.json.JSONObject groupProperties, boolean outOfSession, MiddlewareExtra extra)
void	identify(Identify identify) Identify.
void	identify(Identify identify, boolean outOfSession)
void	identify(Identify identify, boolean outOfSession, MiddlewareExtra extra) Identify.
AmplitudeClient	initialize(android.content.Context context, java.lang.String apiKey) Initialize the Amplitude SDK with the Android application context and your Amplitude App API key.
AmplitudeClient	initialize(android.content.Context context, java.lang.String apiKey, java.lang.String userId) Initialize the Amplitude SDK with the Android application context, your Amplitude App API key, and a user ID for the current user.
AmplitudeClient	initialize(android.content.Context context, java.lang.String apiKey, java.lang.String userId, java.lang.String platform, boolean enableDiagnosticLogging) Initialize the Amplitude SDK with the Android application context, your Amplitude App API key, a user ID for the current user, and a custom platform value.
AmplitudeClient	initialize(android.content.Context context, java.lang.String apiKey, java.lang.String userId, java.lang.String platform, boolean enableDiagnosticLogging, Call.Factory callFactory) Initialize the Amplitude SDK with the Android application context, your Amplitude App API key, a user ID for the current user, and a custom platform value.
protected DeviceInfo	initializeDeviceInfo()
AmplitudeClient	initializeInternal(android.content.Context context, java.lang.String apiKey, java.lang.String userId, java.lang.String platform, boolean enableDiagnosticLogging, Call.Factory callFactory) Initialize the Amplitude SDK with the Android application context, your Amplitude App API key, a user ID for the current user, and a custom platform value.
boolean	isOptedOut() Returns whether or not the user is opted out of tracking.
void	logEvent(java.lang.String eventType) Log an event with the specified event type.
void	logEvent(java.lang.String eventType, org.json.JSONObject eventProperties) Log an event with the specified event type and event properties.
void	logEvent(java.lang.String eventType, org.json.JSONObject eventProperties, boolean outOfSession) Log an event with the specified event type, event properties, with optional out of session flag.
void	logEvent(java.lang.String eventType, org.json.JSONObject eventProperties, org.json.JSONObject groups) Log an event with the specified event type, event properties, and groups.
void	logEvent(java.lang.String eventType, org.json.JSONObject eventProperties, org.json.JSONObject groups, boolean outOfSession) Log event with the specified event type, event properties, groups, with optional out of session flag.
protected long	logEvent(java.lang.String eventType, org.json.JSONObject eventProperties, org.json.JSONObject apiProperties, org.json.JSONObject userProperties, org.json.JSONObject groups, org.json.JSONObject groupProperties, long timestamp, boolean outOfSession) Log event.
protected long	logEvent(java.lang.String eventType, org.json.JSONObject eventProperties, org.json.JSONObject apiProperties, org.json.JSONObject userProperties, org.json.JSONObject groups, org.json.JSONObject groupProperties, long timestamp, boolean outOfSession, MiddlewareExtra extra)
void	logEvent(java.lang.String eventType, org.json.JSONObject eventProperties, org.json.JSONObject groups, long timestamp, boolean outOfSession) Log event with the specified event type, event properties, groups, timestamp, with optional out of session flag.
void	logEvent(java.lang.String eventType, org.json.JSONObject eventProperties, org.json.JSONObject groups, long timestamp, boolean outOfSession, MiddlewareExtra extra)
void	logEvent(java.lang.String eventType, org.json.JSONObject eventProperties, MiddlewareExtra extra) Log an event with the specified event type, event properties, with optional out of session flag.
protected void	logEventAsync(java.lang.String eventType, org.json.JSONObject eventProperties, org.json.JSONObject apiProperties, org.json.JSONObject userProperties, org.json.JSONObject groups, org.json.JSONObject groupProperties, long timestamp, boolean outOfSession) Log event async.
protected void	logEventAsync(java.lang.String eventType, org.json.JSONObject eventProperties, org.json.JSONObject apiProperties, org.json.JSONObject userProperties, org.json.JSONObject groups, org.json.JSONObject groupProperties, long timestamp, boolean outOfSession, MiddlewareExtra extra)
void	logEventSync(java.lang.String eventType) Log an event with the specified event type.
void	logEventSync(java.lang.String eventType, org.json.JSONObject eventProperties) Log an event with the specified event type and event properties.
void	logEventSync(java.lang.String eventType, org.json.JSONObject eventProperties, boolean outOfSession) Log an event with the specified event type, event properties, with optional out of session flag.
void	logEventSync(java.lang.String eventType, org.json.JSONObject eventProperties, org.json.JSONObject groups) Log an event with the specified event type, event properties, and groups.
void	logEventSync(java.lang.String eventType, org.json.JSONObject eventProperties, org.json.JSONObject groups, boolean outOfSession) Log event with the specified event type, event properties, groups, with optional out of session flag.
void	logEventSync(java.lang.String eventType, org.json.JSONObject eventProperties, org.json.JSONObject groups, long timestamp, boolean outOfSession) Log event with the specified event type, event properties, groups, timestamp, with optional sout of ession flag.
void	logRevenue(double amount) Deprecated. - use logRevenueV2 instead
void	logRevenue(java.lang.String productId, int quantity, double price) Deprecated. - use logRevenueV2 instead
void	logRevenue(java.lang.String productId, int quantity, double price, java.lang.String receipt, java.lang.String receiptSignature)
void	logRevenue(java.lang.String productId, int quantity, double price, java.lang.String receipt, java.lang.String receiptSignature, MiddlewareExtra extra) Deprecated. - use logRevenueV2 instead
void	logRevenueV2(Revenue revenue) Log revenue v2.
void	logRevenueV2(Revenue revenue, MiddlewareExtra extra)
protected void	makeEventUploadPostRequest(Call.Factory client, java.lang.String events, long maxEventId, long maxIdentifyId) Internal method to generate the event upload post request.
protected android.util.Pair<android.util.Pair<java.lang.Long,java.lang.Long>,org.json.JSONArray>	mergeEventsAndIdentifys(java.util.List<org.json.JSONObject> events, java.util.List<org.json.JSONObject> identifys, long numEvents) Internal method to merge unsent events and identifies into a single array by sequence number.
AmplitudeClient	regenerateDeviceId() Regenerates a new random deviceId for current user.
protected java.lang.Object	replaceWithJSONNull(java.lang.Object obj) Internal method to replace null event fields with JSON null object.
protected void	runOnLogThread(java.lang.Runnable r)
protected long	saveEvent(java.lang.String eventType, org.json.JSONObject event) Save event.
protected long	saveEvent(java.lang.String eventType, org.json.JSONObject event, MiddlewareExtra extra) Save event long.
AmplitudeClient	setBearerToken(java.lang.String token) Set Bearer Token to be included in request header.
AmplitudeClient	setDeviceId(java.lang.String deviceId) Sets a custom device id.
AmplitudeClient	setDeviceIdCallback(AmplitudeDeviceIdCallback callback)
AmplitudeClient	setDiagnosticEventMaxCount(int eventMaxCount) Deprecated. - We removed Diagnostics class and this function has no-op. Will completely remove it in the near future.
AmplitudeClient	setEventMaxCount(int eventMaxCount) Sets event max count.
AmplitudeClient	setEventUploadMaxBatchSize(int eventUploadMaxBatchSize) Sets event upload max batch size.
AmplitudeClient	setEventUploadPeriodMillis(int eventUploadPeriodMillis) Sets event upload period millis.
AmplitudeClient	setEventUploadThreshold(int eventUploadThreshold) Sets event upload threshold.
AmplitudeClient	setFlushEventsOnClose(boolean flushEventsOnClose) Enable/disable flushing of unsent events on app close (enabled by default).
void	setGroup(java.lang.String groupType, java.lang.Object groupName) Sets the user's group(s).
void	setGroup(java.lang.String groupType, java.lang.Object groupName, MiddlewareExtra extra) Sets the user's group(s).
AmplitudeClient	setIdentifyBatchIntervalMillis(long identifyBatchIntervalMillis) Sets min time for identify batch millis.
AmplitudeClient	setIngestionMetadata(IngestionMetadata ingestionMetadata) Set ingestion metadata information.
AmplitudeClient	setLibraryName(java.lang.String libraryName) Library name is default as `amplitude-android`.
AmplitudeClient	setLibraryVersion(java.lang.String libraryVersion) Library version is default as the latest Amplitude Android SDK version.
AmplitudeClient	setLogCallback(AmplitudeLogCallback callback) Set log callback, it can help read and collect error message from sdk
AmplitudeClient	setLogLevel(int logLevel) Sets the logging level.
AmplitudeClient	setMinTimeBetweenSessionsMillis(long minTimeBetweenSessionsMillis) Sets min time between sessions millis.
AmplitudeClient	setOffline(boolean offline) Sets offline.
AmplitudeClient	setOptOut(boolean optOut) Sets opt out.
AmplitudeClient	setPlan(Plan plan) Set tracking plan information.
AmplitudeClient	setServerUrl(java.lang.String serverUrl) Sets a custom server url for event upload.
AmplitudeClient	setServerZone(AmplitudeServerZone serverZone) Set Amplitude Server Zone, switch to zone related configuration, including dynamic configuration and server url.
AmplitudeClient	setServerZone(AmplitudeServerZone serverZone, boolean updateServerUrl) Set Amplitude Server Zone, switch to zone related configuration, including dynamic configuration.
AmplitudeClient	setSessionTimeoutMillis(long sessionTimeoutMillis) Sets session timeout millis.
AmplitudeClient	setTrackingOptions(TrackingOptions trackingOptions)
AmplitudeClient	setUseDynamicConfig(boolean useDynamicConfig) Turning this flag on will find the best server url automatically based on users' geo location.
AmplitudeClient	setUserId(java.lang.String userId) Sets the user id (can be null).
AmplitudeClient	setUserId(java.lang.String userId, boolean startNewSession) Sets the user id (can be null).
void	setUserProperties(org.json.JSONObject userProperties) Sets user properties.
void	setUserProperties(org.json.JSONObject userProperties, boolean replace) Deprecated.
void	setUserProperties(org.json.JSONObject userProperties, MiddlewareExtra extra) Sets user properties.
void	showEventExplorer(android.app.Activity activity) Show Amplitude Event Explorer for the given activity.
boolean	startNewSessionIfNeeded(long timestamp) Public method to start a new session if needed.
AmplitudeClient	trackSessionEvents(boolean trackingSessionEvents) Track session events amplitude client.
org.json.JSONArray	truncate(org.json.JSONArray array) Truncate values in a JSON array.
org.json.JSONObject	truncate(org.json.JSONObject object) Truncate values in a JSON object.
static java.lang.String	truncate(java.lang.String value) Truncate a string to 1024 characters.
protected void	updateServer() Internal method to upload unsent events.
protected void	updateServer(boolean limit) Internal method to upload unsent events.
void	uploadEvents() Force SDK to upload any unsent events.
AmplitudeClient	useAdvertisingIdForDeviceId() Whether to use the Android advertising ID (ADID) as the user's device ID.
AmplitudeClient	useAppSetIdForDeviceId() Use Android app set id as the user's device ID.
protected boolean	validateLogEvent(java.lang.String eventType) Validate the event type being logged.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

START_SESSION_EVENT

public static final java.lang.String START_SESSION_EVENT

The event type for start session events.

See Also:

Constant Field Values

END_SESSION_EVENT

public static final java.lang.String END_SESSION_EVENT

The event type for end session events.

See Also:

Constant Field Values

DEVICE_ID_KEY

public static final java.lang.String DEVICE_ID_KEY

The pref/database key for the device ID value.

See Also:

Constant Field Values

USER_ID_KEY

public static final java.lang.String USER_ID_KEY

The pref/database key for the user ID value.

See Also:

Constant Field Values

OPT_OUT_KEY

public static final java.lang.String OPT_OUT_KEY

The pref/database key for the opt out flag.

See Also:

Constant Field Values

SEQUENCE_NUMBER_KEY

public static final java.lang.String SEQUENCE_NUMBER_KEY

The pref/database key for the sequence number.

See Also:

Constant Field Values

LAST_EVENT_TIME_KEY

public static final java.lang.String LAST_EVENT_TIME_KEY

The pref/database key for the last event time.

See Also:

Constant Field Values

LAST_EVENT_ID_KEY

public static final java.lang.String LAST_EVENT_ID_KEY

The pref/database key for the last event ID value.

See Also:

Constant Field Values

LAST_IDENTIFY_ID_KEY

public static final java.lang.String LAST_IDENTIFY_ID_KEY

The pref/database key for the last identify ID value.

See Also:

Constant Field Values

PREVIOUS_SESSION_ID_KEY

public static final java.lang.String PREVIOUS_SESSION_ID_KEY

The pref/database key for the previous session ID value.

See Also:

Constant Field Values

context

protected android.content.Context context

The Android App Context.

callFactory

protected Call.Factory callFactory

The shared OkHTTPClient instance.

dbHelper

protected com.amplitude.api.DatabaseHelper dbHelper

The shared Amplitude database helper instance.

apiKey

protected java.lang.String apiKey

The Amplitude App API key.

instanceName

protected java.lang.String instanceName

The name for this instance of AmplitudeClient.

userId

protected java.lang.String userId

The user's ID value.

deviceId

protected java.lang.String deviceId

The user's Device ID value.

initialized

protected boolean initialized

platform

protected java.lang.String platform

The device's Platform value.

deviceInfo

protected DeviceInfo deviceInfo

Constructor Detail

AmplitudeClient

public AmplitudeClient()

Instantiates a new default instance AmplitudeClient and starts worker threads.

AmplitudeClient

public AmplitudeClient(java.lang.String instance)

Instantiates a new AmplitudeClient with instance name and starts worker threads.

Parameters:

instance -

Method Detail

initialize

public AmplitudeClient initialize(android.content.Context context,
                                  java.lang.String apiKey)

Initialize the Amplitude SDK with the Android application context and your Amplitude App API key. Note: initialization is required before you log events and modify user properties.

Parameters:

context - the Android application context

apiKey - your Amplitude App API key

Returns:

the AmplitudeClient

initialize

public AmplitudeClient initialize(android.content.Context context,
                                  java.lang.String apiKey,
                                  java.lang.String userId)

Initialize the Amplitude SDK with the Android application context, your Amplitude App API key, and a user ID for the current user. Note: initialization is required before you log events and modify user properties.

Parameters:

context - the Android application context

apiKey - your Amplitude App API key

userId - the user id to set

Returns:

the AmplitudeClient

initialize

public AmplitudeClient initialize(android.content.Context context,
                                  java.lang.String apiKey,
                                  java.lang.String userId,
                                  java.lang.String platform,
                                  boolean enableDiagnosticLogging)

Initialize the Amplitude SDK with the Android application context, your Amplitude App API key, a user ID for the current user, and a custom platform value. Note: initialization is required before you log events and modify user properties.

Parameters:

context - the Android application context

apiKey - your Amplitude App API key

userId - the user id to set

-

Returns:

the AmplitudeClient

initialize

public AmplitudeClient initialize(android.content.Context context,
                                  java.lang.String apiKey,
                                  java.lang.String userId,
                                  java.lang.String platform,
                                  boolean enableDiagnosticLogging,
                                  Call.Factory callFactory)

Initialize the Amplitude SDK with the Android application context, your Amplitude App API key, a user ID for the current user, and a custom platform value. Note: initialization is required before you log events and modify user properties.

Parameters:

context - the Android application context

apiKey - your Amplitude App API key

userId - the user id to set

callFactory - the call factory that used by Amplitude to make http request

Returns:

the AmplitudeClient

initializeInternal

public AmplitudeClient initializeInternal(android.content.Context context,
                                          java.lang.String apiKey,
                                          java.lang.String userId,
                                          java.lang.String platform,
                                          boolean enableDiagnosticLogging,
                                          Call.Factory callFactory)

Initialize the Amplitude SDK with the Android application context, your Amplitude App API key, a user ID for the current user, and a custom platform value. Note: initialization is required before you log events and modify user properties.

Parameters:

context - the Android application context

apiKey - your Amplitude App API key

userId - the user id to set

-

Returns:

the AmplitudeClient

enableForegroundTracking

public AmplitudeClient enableForegroundTracking(android.app.Application app)

Enable foreground tracking for the SDK. This is HIGHLY RECOMMENDED, and will allow for accurate session tracking.

Parameters:

app - the Android application

Returns:

the AmplitudeClient

See Also:

Tracking Sessions

enableDiagnosticLogging

public AmplitudeClient enableDiagnosticLogging()

Deprecated. - We removed Diagnostics class and this function has no-op. Will completely remove it in the near future.

disableDiagnosticLogging

public AmplitudeClient disableDiagnosticLogging()

Deprecated. - We removed Diagnostics class and this function has no-op. Will completely remove it in the near future.

setDiagnosticEventMaxCount

public AmplitudeClient setDiagnosticEventMaxCount(int eventMaxCount)

Deprecated. - We removed Diagnostics class and this function has no-op. Will completely remove it in the near future.

enableNewDeviceIdPerInstall

public AmplitudeClient enableNewDeviceIdPerInstall(boolean newDeviceIdPerInstall)

Deprecated.

Whether to set a new device ID per install. If true, then the SDK will always generate a new device ID on app install (as opposed to re-using an existing value like ADID).

Parameters:

newDeviceIdPerInstall - whether to set a new device ID on app install.

Returns:

the AmplitudeClient

useAdvertisingIdForDeviceId

public AmplitudeClient useAdvertisingIdForDeviceId()

Whether to use the Android advertising ID (ADID) as the user's device ID.

Returns:

the AmplitudeClient

useAppSetIdForDeviceId

public AmplitudeClient useAppSetIdForDeviceId()

Use Android app set id as the user's device ID.

Returns:

the AmplitudeClient

enableLocationListening

public AmplitudeClient enableLocationListening()

Enable location listening in the SDK. This will add the user's current lat/lon coordinates to every event logged. This function should be called before SDK initialization, e.g. initialize(Context, String).

Returns:

the AmplitudeClient

disableLocationListening

public AmplitudeClient disableLocationListening()

Disable location listening in the SDK. This will stop the sending of the user's current lat/lon coordinates. This function should be called before SDK initialization, e.g. initialize(Context, String).

Returns:

the AmplitudeClient

setEventUploadThreshold

public AmplitudeClient setEventUploadThreshold(int eventUploadThreshold)

Sets event upload threshold. The SDK will attempt to batch upload unsent events every eventUploadPeriodMillis milliseconds, or if the unsent event count exceeds the event upload threshold.

Parameters:

eventUploadThreshold - the event upload threshold

Returns:

the AmplitudeClient

setEventUploadMaxBatchSize

public AmplitudeClient setEventUploadMaxBatchSize(int eventUploadMaxBatchSize)

Sets event upload max batch size. This controls the maximum number of events sent with each upload request.

Parameters:

eventUploadMaxBatchSize - the event upload max batch size

Returns:

the AmplitudeClient

setEventMaxCount

public AmplitudeClient setEventMaxCount(int eventMaxCount)

Sets event max count. This is the maximum number of unsent events to keep on the device (for example if the device does not have internet connectivity and cannot upload events). If the number of unsent events exceeds the max count, then the SDK begins dropping events, starting from the earliest logged.

Parameters:

eventMaxCount - the event max count

Returns:

the AmplitudeClient

setEventUploadPeriodMillis

public AmplitudeClient setEventUploadPeriodMillis(int eventUploadPeriodMillis)

Sets event upload period millis. The SDK will attempt to batch upload unsent events every eventUploadPeriodMillis milliseconds, or if the unsent event count exceeds the event upload threshold.

Parameters:

eventUploadPeriodMillis - the event upload period millis

Returns:

the AmplitudeClient

setMinTimeBetweenSessionsMillis

public AmplitudeClient setMinTimeBetweenSessionsMillis(long minTimeBetweenSessionsMillis)

Sets min time between sessions millis.

Parameters:

minTimeBetweenSessionsMillis - the min time between sessions millis

Returns:

the min time between sessions millis

setIdentifyBatchIntervalMillis

public AmplitudeClient setIdentifyBatchIntervalMillis(long identifyBatchIntervalMillis)

Sets min time for identify batch millis.

Parameters:

identifyBatchIntervalMillis - the time interval for identify batch interval

Returns:

the AmplitudeClient

setServerUrl

public AmplitudeClient setServerUrl(java.lang.String serverUrl)

Sets a custom server url for event upload. We now have a new method setServerZone. To send data to Amplitude's EU servers, recommend to use setServerZone method like client.setServerZone(AmplitudeServerZone.EU);

Parameters:

serverUrl - - a string url for event upload.

Returns:

the AmplitudeClient

setBearerToken

public AmplitudeClient setBearerToken(java.lang.String token)

Set Bearer Token to be included in request header.

Parameters:

token -

Returns:

the AmplitudeClient

setSessionTimeoutMillis

public AmplitudeClient setSessionTimeoutMillis(long sessionTimeoutMillis)

Sets session timeout millis. If foreground tracking has not been enabled with

Parameters:

sessionTimeoutMillis - the session timeout millis

Returns:

the AmplitudeClient

setTrackingOptions

public AmplitudeClient setTrackingOptions(TrackingOptions trackingOptions)

enableCoppaControl

public AmplitudeClient enableCoppaControl()

Enable COPPA (Children's Online Privacy Protection Act) restrictions on ADID, city, IP address and location tracking. This can be used by any customer that does not want to collect ADID, city, IP address and location tracking.

disableCoppaControl

public AmplitudeClient disableCoppaControl()

Disable COPPA (Children's Online Privacy Protection Act) restrictions on ADID, city, IP address and location tracking.

setOptOut

public AmplitudeClient setOptOut(boolean optOut)

Sets opt out. If true then the SDK does not track any events for the user.

Parameters:

optOut - whether or not to opt the user out of tracking

Returns:

the AmplitudeClient

setLibraryName

public AmplitudeClient setLibraryName(java.lang.String libraryName)

Library name is default as `amplitude-android`. Notice: You will only want to set it when following conditions are met. 1. You develop your own library which bridges Amplitude Android native library. 2. You want to track your library as one of the data sources.

setLibraryVersion

public AmplitudeClient setLibraryVersion(java.lang.String libraryVersion)

Library version is default as the latest Amplitude Android SDK version. Notice: You will only want to set it when following conditions are met. 1. You develop your own library which bridges Amplitude Android native library. 2. You want to track your library as one of the data sources.

isOptedOut

public boolean isOptedOut()

Returns whether or not the user is opted out of tracking.

Returns:

the optOut flag value

enableLogging

public AmplitudeClient enableLogging(boolean enableLogging)

Enable/disable message logging by the SDK.

Parameters:

enableLogging - whether to enable message logging by the SDK.

Returns:

the AmplitudeClient

setLogLevel

public AmplitudeClient setLogLevel(int logLevel)

Sets the logging level. Logging messages will only appear if they are the same severity level or higher than the set log level.

Parameters:

logLevel - the log level

Returns:

the AmplitudeClient

setLogCallback

public AmplitudeClient setLogCallback(AmplitudeLogCallback callback)

Set log callback, it can help read and collect error message from sdk

Parameters:

callback -

Returns:

the AmplitudeClient

setOffline

public AmplitudeClient setOffline(boolean offline)

Sets offline. If offline is true, then the SDK will not upload events to Amplitude servers; however, it will still log events.

Parameters:

offline - whether or not the SDK should be offline

Returns:

the AmplitudeClient

setFlushEventsOnClose

public AmplitudeClient setFlushEventsOnClose(boolean flushEventsOnClose)

Enable/disable flushing of unsent events on app close (enabled by default).

Parameters:

flushEventsOnClose - whether to flush unsent events on app close

Returns:

the AmplitudeClient

trackSessionEvents

public AmplitudeClient trackSessionEvents(boolean trackingSessionEvents)

Track session events amplitude client. If enabled then the SDK will automatically send start and end session events to mark the start and end of the user's sessions.

Parameters:

trackingSessionEvents - whether to enable tracking of session events

Returns:

the AmplitudeClient

setUseDynamicConfig

public AmplitudeClient setUseDynamicConfig(boolean useDynamicConfig)

Turning this flag on will find the best server url automatically based on users' geo location. Note: 1. If you have your own proxy server and use `setServerUrl` API, please leave this off. 2. If you have users in China Mainland, we suggest you turn this on.

Parameters:

useDynamicConfig - whether to enable dynamic config

Returns:

the AmplitudeClient

showEventExplorer

public void showEventExplorer(android.app.Activity activity)

Show Amplitude Event Explorer for the given activity.

Parameters:

activity - root activity

addEventMiddleware

public void addEventMiddleware(Middleware middleware)

Add middleware to the middleware runner

logEvent

public void logEvent(java.lang.String eventType)

Log an event with the specified event type. Note: this is asynchronous and happens on a background thread.

Parameters:

eventType - the event type

logEvent

public void logEvent(java.lang.String eventType,
                     org.json.JSONObject eventProperties)

Log an event with the specified event type and event properties. Note: this is asynchronous and happens on a background thread.

Parameters:

eventType - the event type

eventProperties - the event properties

logEvent

public void logEvent(java.lang.String eventType,
                     org.json.JSONObject eventProperties,
                     MiddlewareExtra extra)

Log an event with the specified event type, event properties, with optional out of session flag. If out of session is true, then the sessionId will be -1 for the event, indicating that it is not part of the current session. Note: this might be useful when logging events for notifications received. Note: this is asynchronous and happens on a background thread.

Parameters:

eventType - the event type

eventProperties - the event properties

extra - the extra unstructured data for middleware

logEvent

public void logEvent(java.lang.String eventType,
                     org.json.JSONObject eventProperties,
                     boolean outOfSession)

Log an event with the specified event type, event properties, with optional out of session flag. If out of session is true, then the sessionId will be -1 for the event, indicating that it is not part of the current session. Note: this might be useful when logging events for notifications received. Note: this is asynchronous and happens on a background thread.

Parameters:

eventType - the event type

eventProperties - the event properties

outOfSession - the out of session

logEvent

public void logEvent(java.lang.String eventType,
                     org.json.JSONObject eventProperties,
                     org.json.JSONObject groups)

Log an event with the specified event type, event properties, and groups. Use this to set event-level groups, meaning the group(s) set only apply for this specific event and does not persist on the user. Note: this is asynchronous and happens on a background thread.

Parameters:

eventType - the event type

eventProperties - the event properties

groups - the groups

logEvent

public void logEvent(java.lang.String eventType,
                     org.json.JSONObject eventProperties,
                     org.json.JSONObject groups,
                     boolean outOfSession)

Log event with the specified event type, event properties, groups, with optional out of session flag. If out of session is true, then the sessionId will be -1 for the event, indicating that it is not part of the current session. Note: this might be useful when logging events for notifications received. Note: this is asynchronous and happens on a background thread.

Parameters:

eventType - the event type

eventProperties - the event properties

groups - the groups

outOfSession - the out of session

logEvent

public void logEvent(java.lang.String eventType,
                     org.json.JSONObject eventProperties,
                     org.json.JSONObject groups,
                     long timestamp,
                     boolean outOfSession)

Log event with the specified event type, event properties, groups, timestamp, with optional out of session flag. If out of session is true, then the sessionId will be -1 for the event, indicating that it is not part of the current session. Note: this might be useful when logging events for notifications received. Note: this is asynchronous and happens on a background thread.

Parameters:

eventType - the event type

eventProperties - the event properties

groups - the groups

timestamp - the timestamp in millisecond since epoch

outOfSession - the out of session

See Also:

Setting Event Properties, Setting Groups, Tracking Sessions

logEvent

public void logEvent(java.lang.String eventType,
                     org.json.JSONObject eventProperties,
                     org.json.JSONObject groups,
                     long timestamp,
                     boolean outOfSession,
                     MiddlewareExtra extra)

logEventSync

public void logEventSync(java.lang.String eventType)

Log an event with the specified event type. Note: this is version is synchronous and blocks the main thread until done.

Parameters:

eventType - the event type

logEventSync

public void logEventSync(java.lang.String eventType,
                         org.json.JSONObject eventProperties)

Log an event with the specified event type and event properties. Note: this is version is synchronous and blocks the main thread until done.

Parameters:

eventType - the event type

eventProperties - the event properties

See Also:

Setting Event Properties

logEventSync

public void logEventSync(java.lang.String eventType,
                         org.json.JSONObject eventProperties,
                         boolean outOfSession)

Log an event with the specified event type, event properties, with optional out of session flag. If out of session is true, then the sessionId will be -1 for the event, indicating that it is not part of the current session. Note: this might be useful when logging events for notifications received. Note: this is version is synchronous and blocks the main thread until done.

Parameters:

eventType - the event type

eventProperties - the event properties

outOfSession - the out of session

logEventSync

public void logEventSync(java.lang.String eventType,
                         org.json.JSONObject eventProperties,
                         org.json.JSONObject groups)

Log an event with the specified event type, event properties, and groups. Use this to set event-level groups, meaning the group(s) set only apply for this specific event and does not persist on the user. Note: this is version is synchronous and blocks the main thread until done.

Parameters:

eventType - the event type

eventProperties - the event properties

groups - the groups

logEventSync

public void logEventSync(java.lang.String eventType,
                         org.json.JSONObject eventProperties,
                         org.json.JSONObject groups,
                         boolean outOfSession)

Log event with the specified event type, event properties, groups, with optional out of session flag. If out of session is true, then the sessionId will be -1 for the event, indicating that it is not part of the current session. Note: this might be useful when logging events for notifications received. Note: this is version is synchronous and blocks the main thread until done.

Parameters:

eventType - the event type

eventProperties - the event properties

groups - the groups

outOfSession - the out of session

See Also:

Setting Event Properties, Setting Groups, Tracking Sessions

logEventSync

public void logEventSync(java.lang.String eventType,
                         org.json.JSONObject eventProperties,
                         org.json.JSONObject groups,
                         long timestamp,
                         boolean outOfSession)

Log event with the specified event type, event properties, groups, timestamp, with optional sout of ession flag. If out of session is true, then the sessionId will be -1 for the event, indicating that it is not part of the current session. Note: this might be useful when logging events for notifications received. Note: this is version is synchronous and blocks the main thread until done.

Parameters:

eventType - the event type

eventProperties - the event properties

groups - the groups

timestamp - the timestamp in milliseconds since epoch

outOfSession - the out of session

validateLogEvent

protected boolean validateLogEvent(java.lang.String eventType)

Validate the event type being logged. Also verifies that the context and API key have been set already with an initialize call.

Parameters:

eventType - the event type

Returns:

true if the event type is valid

logEventAsync

protected void logEventAsync(java.lang.String eventType,
                             org.json.JSONObject eventProperties,
                             org.json.JSONObject apiProperties,
                             org.json.JSONObject userProperties,
                             org.json.JSONObject groups,
                             org.json.JSONObject groupProperties,
                             long timestamp,
                             boolean outOfSession)

Log event async. Internal method to handle the synchronous logging of events.

Parameters:

eventType - the event type

eventProperties - the event properties

apiProperties - the api properties

userProperties - the user properties

groups - the groups

timestamp - the timestamp

outOfSession - the out of session

logEventAsync

protected void logEventAsync(java.lang.String eventType,
                             org.json.JSONObject eventProperties,
                             org.json.JSONObject apiProperties,
                             org.json.JSONObject userProperties,
                             org.json.JSONObject groups,
                             org.json.JSONObject groupProperties,
                             long timestamp,
                             boolean outOfSession,
                             MiddlewareExtra extra)

logEvent

protected long logEvent(java.lang.String eventType,
                        org.json.JSONObject eventProperties,
                        org.json.JSONObject apiProperties,
                        org.json.JSONObject userProperties,
                        org.json.JSONObject groups,
                        org.json.JSONObject groupProperties,
                        long timestamp,
                        boolean outOfSession)

Log event. Internal method to handle the asynchronous logging of events on background thread.

Parameters:

eventType - the event type

eventProperties - the event properties

apiProperties - the api properties

userProperties - the user properties

groups - the groups

timestamp - the timestamp

outOfSession - the out of session

Returns:

the event ID if succeeded, else -1.

logEvent

protected long logEvent(java.lang.String eventType,
                        org.json.JSONObject eventProperties,
                        org.json.JSONObject apiProperties,
                        org.json.JSONObject userProperties,
                        org.json.JSONObject groups,
                        org.json.JSONObject groupProperties,
                        long timestamp,
                        boolean outOfSession,
                        MiddlewareExtra extra)

saveEvent

protected long saveEvent(java.lang.String eventType,
                         org.json.JSONObject event,
                         MiddlewareExtra extra)

Save event long. Internal method to save an event to the database.

Parameters:

eventType - the event type

event - the event

extra - the extra unstructured data for middleware

Returns:

the event ID if succeeded, else -1

saveEvent

protected long saveEvent(java.lang.String eventType,
                         org.json.JSONObject event)

Save event. Internal method to save an event.

Parameters:

eventType - the event type

event - the event

Returns:

the event ID if succeeded, else -1

getSessionId

public long getSessionId()

Gets the current session id.

Returns:

The current sessionId value.

startNewSessionIfNeeded

public boolean startNewSessionIfNeeded(long timestamp)

Public method to start a new session if needed.

Parameters:

timestamp - the timestamp

Returns:

whether or not a new session was started

logRevenue

public void logRevenue(double amount)

Deprecated. - use logRevenueV2 instead

Log revenue amount via a revenue event.

Parameters:

amount - the amount

See Also:

Tracking Revenue

logRevenue

public void logRevenue(java.lang.String productId,
                       int quantity,
                       double price)

Deprecated. - use logRevenueV2 instead

Log revenue with a productId, quantity, and price.

Parameters:

productId - the product id

quantity - the quantity

price - the price

See Also:

Tracking Revenue

logRevenue

public void logRevenue(java.lang.String productId,
                       int quantity,
                       double price,
                       java.lang.String receipt,
                       java.lang.String receiptSignature)

logRevenue

public void logRevenue(java.lang.String productId,
                       int quantity,
                       double price,
                       java.lang.String receipt,
                       java.lang.String receiptSignature,
                       MiddlewareExtra extra)

Deprecated. - use logRevenueV2 instead

Log revenue with a productId, quantity, price, and receipt data for revenue verification.

Parameters:

productId - the product id

quantity - the quantity

price - the price

receipt - the receipt

receiptSignature - the receipt signature

extra - the extra unstructured data for middleware

See Also:

Tracking Revenue

logRevenueV2

public void logRevenueV2(Revenue revenue)

Log revenue v2. Create a Revenue object to hold your revenue data and properties, and log it as a revenue event using this method.

Parameters:

revenue - a Revenue object

logRevenueV2

public void logRevenueV2(Revenue revenue,
                         MiddlewareExtra extra)

setUserProperties

public void setUserProperties(org.json.JSONObject userProperties,
                              boolean replace)

Deprecated.

Sets user properties. This is a convenience wrapper around the Identify API to set multiple user properties with a single command. Note: the replace parameter is deprecated and has no effect.

Parameters:

userProperties - the user properties

replace - the replace - has no effect

setUserProperties

public void setUserProperties(org.json.JSONObject userProperties)

Sets user properties. This is a convenience wrapper around the Identify API to set multiple user properties with a single command.

Parameters:

userProperties - the user properties

setUserProperties

public void setUserProperties(org.json.JSONObject userProperties,
                              MiddlewareExtra extra)

Sets user properties. This is a convenience wrapper around the Identify API to set multiple user properties with a single command.

Parameters:

userProperties - the user properties

extra - the extra unstructured data for middleware

clearUserProperties

public void clearUserProperties()

Clear user properties. This will clear all user properties at once. Note: the result is irreversible!

identify

public void identify(Identify identify)

Identify. Use this to send an Identify object containing user property operations to Amplitude server.

Parameters:

identify - an Identify object

identify

public void identify(Identify identify,
                     boolean outOfSession)

identify

public void identify(Identify identify,
                     boolean outOfSession,
                     MiddlewareExtra extra)

Identify. Use this to send an Identify object containing user property operations to Amplitude server. If outOfSession is true, then the identify event is sent with a session id of -1, and does not trigger any session-handling logic.

Parameters:

identify - an Identify object

outOfSession - whther to log the identify event out of session

extra - the extra unstructured data for middleware

setGroup

public void setGroup(java.lang.String groupType,
                     java.lang.Object groupName)

Sets the user's group(s).

Parameters:

groupType - the group type (ex: orgId)

groupName - the group name (ex: 15)

setGroup

public void setGroup(java.lang.String groupType,
                     java.lang.Object groupName,
                     MiddlewareExtra extra)

Sets the user's group(s).

Parameters:

groupType - the group type (ex: orgId)

groupName - the group name (ex: 15)

extra - the extra unstructured data for middleware

groupIdentify

public void groupIdentify(java.lang.String groupType,
                          java.lang.Object groupName,
                          Identify groupIdentify)

groupIdentify

public void groupIdentify(java.lang.String groupType,
                          java.lang.Object groupName,
                          Identify groupIdentify,
                          boolean outOfSession)

groupIdentify

public void groupIdentify(java.lang.String groupType,
                          java.lang.Object groupName,
                          org.json.JSONObject groupProperties,
                          boolean outOfSession,
                          MiddlewareExtra extra)

groupIdentify

public void groupIdentify(java.lang.String groupType,
                          java.lang.Object groupName,
                          Identify groupIdentify,
                          boolean outOfSession,
                          MiddlewareExtra extra)

truncate

public org.json.JSONObject truncate(org.json.JSONObject object)

Truncate values in a JSON object. Any string values longer than 1024 characters will be truncated to 1024 characters. Any dictionary with more than 1000 items will be ignored.

Parameters:

object - the object

Returns:

the truncated JSON object

truncate

public org.json.JSONArray truncate(org.json.JSONArray array)
                            throws org.json.JSONException

Truncate values in a JSON array. Any string values longer than 1024 characters will be truncated to 1024 characters.

Parameters:

array - the array

Returns:

the truncated JSON array

Throws:

org.json.JSONException - the json exception

truncate

public static java.lang.String truncate(java.lang.String value)

Truncate a string to 1024 characters.

Parameters:

value - the value

Returns:

the truncated string

getUserId

public java.lang.String getUserId()

Gets the user's id. Can be null.

Returns:

The developer specified identifier for tracking within the analytics system.

setUserId

public AmplitudeClient setUserId(java.lang.String userId)

Sets the user id (can be null).

Parameters:

userId - the user id

Returns:

the AmplitudeClient

setUserId

public AmplitudeClient setUserId(java.lang.String userId,
                                 boolean startNewSession)

Sets the user id (can be null). If startNewSession is true, ends the session for the previous user and starts a new session for the new user id.

Parameters:

userId - the user id

Returns:

the AmplitudeClient

setDeviceId

public AmplitudeClient setDeviceId(java.lang.String deviceId)

Sets a custom device id. Note: only do this if you know what you are doing!

Parameters:

deviceId - the device id

Returns:

the AmplitudeClient

regenerateDeviceId

public AmplitudeClient regenerateDeviceId()

Regenerates a new random deviceId for current user. Note: this is not recommended unless you know what you are doing. This can be used in conjunction with setUserId(null) to anonymize users after they log out. With a null userId and a completely new deviceId, the current user would appear as a brand new user in dashboard.

uploadEvents

public void uploadEvents()

Force SDK to upload any unsent events.

updateServer

protected void updateServer()

Internal method to upload unsent events.

updateServer

protected void updateServer(boolean limit)

Internal method to upload unsent events. Limit controls whether to use event upload max batch size or backoff upload batch size. Note: always call this on logThread

Parameters:

limit - the limit

mergeEventsAndIdentifys

protected android.util.Pair<android.util.Pair<java.lang.Long,java.lang.Long>,org.json.JSONArray> mergeEventsAndIdentifys(java.util.List<org.json.JSONObject> events,
                                                                                                                         java.util.List<org.json.JSONObject> identifys,
                                                                                                                         long numEvents)
                                                                                                                  throws org.json.JSONException

Internal method to merge unsent events and identifies into a single array by sequence number.

Parameters:

events - the events

identifys - the identifys

numEvents - the num events

Returns:

the merged array, max event id, and max identify id

Throws:

org.json.JSONException - the json exception

makeEventUploadPostRequest

protected void makeEventUploadPostRequest(Call.Factory client,
                                          java.lang.String events,
                                          long maxEventId,
                                          long maxIdentifyId)

Internal method to generate the event upload post request.

Parameters:

client - the client

events - the events

maxEventId - the max event id

maxIdentifyId - the max identify id

initializeDeviceInfo

protected DeviceInfo initializeDeviceInfo()

getDeviceId

public java.lang.String getDeviceId()

Get the current device id. Can be null if deviceId hasn't been initialized yet.

Returns:

A unique identifier for tracking within the analytics system.

setDeviceIdCallback

public AmplitudeClient setDeviceIdCallback(AmplitudeDeviceIdCallback callback)

runOnLogThread

protected void runOnLogThread(java.lang.Runnable r)

replaceWithJSONNull

protected java.lang.Object replaceWithJSONNull(java.lang.Object obj)

Internal method to replace null event fields with JSON null object.

Parameters:

obj - the obj

Returns:

the object

contextAndApiKeySet

protected boolean contextAndApiKeySet(java.lang.String methodName)

Internal method to check whether application context and api key are set

Parameters:

methodName - the parent method name to print in error message

Returns:

whether application context and api key are set

bytesToHexString

protected java.lang.String bytesToHexString(byte[] bytes)

Internal method to convert bytes to hex string

Parameters:

bytes - the bytes

Returns:

the string

getCurrentTimeMillis

protected long getCurrentTimeMillis()

Internal method to fetch the current time millis. Used for testing.

Returns:

the current time millis

setPlan

public AmplitudeClient setPlan(Plan plan)

Set tracking plan information.

Parameters:

plan - Plan object

Returns:

the AmplitudeClient

setIngestionMetadata

public AmplitudeClient setIngestionMetadata(IngestionMetadata ingestionMetadata)

Set ingestion metadata information.

Parameters:

ingestionMetadata - IngestionMetadata object

Returns:

the AmplitudeClient

setServerZone

public AmplitudeClient setServerZone(AmplitudeServerZone serverZone)

Set Amplitude Server Zone, switch to zone related configuration, including dynamic configuration and server url. To send data to Amplitude's EU servers, you need to configure the serverZone to EU like client.setServerZone(AmplitudeServerZone.EU);

Parameters:

serverZone - AmplitudeServerZone, US or EU, default is US

Returns:

the AmplitudeClient

setServerZone

public AmplitudeClient setServerZone(AmplitudeServerZone serverZone,
                                     boolean updateServerUrl)

Set Amplitude Server Zone, switch to zone related configuration, including dynamic configuration. If updateServerUrl is true, including server url as well. Recommend to keep updateServerUrl to be true for alignment.

Parameters:

serverZone - AmplitudeServerZone, US or EU, default is US

updateServerUrl - if update server url when update server zone, recommend setting true

Returns:

getServerZone

public AmplitudeServerZone getServerZone()

Get Amplitude Server Zone

Returns:

the current Amplitude Server Zone