com.segment.analytics

Class Analytics

java.lang.Object

com.segment.analytics.Analytics

public class Analytics
extends java.lang.Object

The entry point into the Segment for Android SDK.

The idea is simple: one pipeline for all your data. Segment is the single hub to collect, translate and route your data with the flip of a switch.

Analytics for Android will automatically batch events, queue them to disk, and upload it periodically to Segment for you. It will also look up your project's settings (that you've configured in the web interface), specifically looking up settings for bundled integrations, and then initialize them for you on the user's phone, and mapping our standardized events to formats they can all understand. You only need to instrument Segment once, then flip a switch to install new tools.

This class is the main entry point into the client API. Use with(android.content.Context) for the global singleton instance or construct your own instance with Analytics.Builder.

See Also:

Segment

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Analytics.Builder Fluent API for creating Analytics instances.
static class	Analytics.BundledIntegration Deprecated.
static interface	Analytics.Callback<T> A callback interface that is invoked when the Analytics client initializes bundled integrations.
static class	Analytics.LogLevel Controls the level of logging.

Method Summary

Modifier and Type	Method and Description
void	alias(java.lang.String newId)
void	alias(java.lang.String newId, Options options) The alias method is used to merge two user identities, effectively connecting two sets of user data as one.
void	flush() Asynchronously flushes all messages in the queue to the server, and tells bundled integrations to do the same.
AnalyticsContext	getAnalyticsContext() Get the AnalyticsContext used by this instance.
android.app.Application	getApplication() Return the Application used to create this instance.
Logger	getLogger() Deprecated. This will be removed in a future release.
Analytics.LogLevel	getLogLevel() Deprecated. This will be removed in a future release.
StatsSnapshot	getSnapshot() Creates a StatsSnapshot of the current stats for this instance.
void	group(java.lang.String groupId)
void	group(java.lang.String groupId, Traits traits)
void	group(java.lang.String groupId, Traits groupTraits, Options options) The group method lets you associate a user with a group.
void	identify(java.lang.String userId)
void	identify(java.lang.String userId, Traits newTraits, Options options) Identify lets you tie one of your users and their actions to a recognizable userId.
void	identify(Traits traits)
Logger	logger(java.lang.String tag) Return a new Logger with the given sub-tag.
void	logout() Deprecated. Use reset() instead
void	onIntegrationReady(Analytics.BundledIntegration integration, Analytics.Callback callback) Deprecated. Use onIntegrationReady(String, Callback) instead.
<T> void	onIntegrationReady(java.lang.String key, Analytics.Callback<T> callback) Register to be notified when a bundled integration is ready.
void	optOut(boolean optOut) Set the opt-out status for the current device and analytics client combination.
void	reset() Resets the analytics client by clearing any stored information about the user.
void	screen(java.lang.String name)
void	screen(java.lang.String name, Properties properties)
void	screen(java.lang.String category, java.lang.String name) Deprecated. Use screen(String) instead.
void	screen(java.lang.String category, java.lang.String name, Properties properties) Deprecated. Use screen(String, Properties) instead.
void	screen(java.lang.String category, java.lang.String name, Properties properties, Options options) The screen methods let your record whenever a user sees a screen of your mobile app, and attach a name, category or properties to the screen.
static void	setSingletonInstance(Analytics analytics) Set the global instance returned from with(android.content.Context).
void	shutdown() Stops this instance from accepting further requests.
void	track(java.lang.String event)
void	track(java.lang.String event, Properties properties)
void	track(java.lang.String event, Properties properties, Options options) The track method is how you record any actions your users perform.
static Analytics	with(android.content.Context context) Return a reference to the global default Analytics instance.

Methods inherited from class java.lang.Object

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

Method Detail

with

public static Analytics with(android.content.Context context)

Return a reference to the global default Analytics instance.

This instance is automatically initialized with defaults that are suitable to most implementations.

If these settings do not meet the requirements of your application, you can override defaults in analytics.xml, or you can construct your own instance with full control over the configuration by using Analytics.Builder.

By default, events are uploaded every 30 seconds, or every 20 events (whichever occurs first), and debugging is disabled.

setSingletonInstance

public static void setSingletonInstance(Analytics analytics)

Set the global instance returned from with(android.content.Context).

This method must be called before any calls to with(android.content.Context) and may only be called once.

identify

public void identify(@NonNull
                     java.lang.String userId)

See Also:

identify(String, Traits, Options)

identify

public void identify(@NonNull
                     Traits traits)

See Also:

identify(String, Traits, Options)

identify

public void identify(@Nullable
                     java.lang.String userId,
                     @Nullable
                     Traits newTraits,
                     @Nullable
                     Options options)

Identify lets you tie one of your users and their actions to a recognizable userId. It also lets you record traits about the user, like their email, name, account type, etc.

Traits and userId will be automatically cached and available on future sessions for the same user. To update a trait on the server, call identify with the same user id (or null). You can also use identify(Traits) for this purpose.

Parameters:

userId - Unique identifier which you recognize a user by in your own database. If this is null or empty, any previous id we have (could be the anonymous id) will be used.

newTraits - Traits about the user.

options - To configure the call.

Throws:

java.lang.IllegalArgumentException - if both userId and newTraits are not provided

See Also:

Identify Documentation

group

public void group(@NonNull
                  java.lang.String groupId)

See Also:

group(String, Traits, Options)

group

public void group(@NonNull
                  java.lang.String groupId,
                  @Nullable
                  Traits traits)

See Also:

group(String, Traits, Options)

group

public void group(@NonNull
                  java.lang.String groupId,
                  @Nullable
                  Traits groupTraits,
                  @Nullable
                  Options options)

The group method lets you associate a user with a group. It also lets you record custom traits about the group, like industry or number of employees.

If you've called identify(String, Traits, Options) before, this will automatically remember the userId. If not, it will fall back to use the anonymousId instead.

Parameters:

groupId - Unique identifier which you recognize a group by in your own database. Must not be null or empty.

options - To configure the call.

Throws:

java.lang.IllegalArgumentException - if groupId is null or an empty string.

See Also:

Group Documentation

track

public void track(@NonNull
                  java.lang.String event)

See Also:

track(String, Properties, Options)

track

public void track(@NonNull
                  java.lang.String event,
                  @Nullable
                  Properties properties)

See Also:

track(String, Properties, Options)

track

public void track(@NonNull
                  java.lang.String event,
                  @Nullable
                  Properties properties,
                  @Nullable
                  Options options)

The track method is how you record any actions your users perform. Each action is known by a name, like 'Purchased a T-Shirt'. You can also record properties specific to those actions. For example a 'Purchased a Shirt' event might have properties like revenue or size.

Parameters:

event - Name of the event. Must not be null or empty.

properties - Properties to add extra information to this call.

options - To configure the call.

Throws:

java.lang.IllegalArgumentException - if event name is null or an empty string.

See Also:

Track Documentation

screen

public void screen(@Nullable
                   java.lang.String category,
                   @Nullable
                   java.lang.String name)

Deprecated. Use screen(String) instead.

See Also:

screen(String, String, Properties, Options)

screen

public void screen(@Nullable
                   java.lang.String category,
                   @Nullable
                   java.lang.String name,
                   @Nullable
                   Properties properties)

Deprecated. Use screen(String, Properties) instead.

See Also:

screen(String, String, Properties, Options)

screen

public void screen(@Nullable
                   java.lang.String name)

See Also:

screen(String, String, Properties, Options)

screen

public void screen(@Nullable
                   java.lang.String name,
                   @Nullable
                   Properties properties)

See Also:

screen(String, String, Properties, Options)

screen

public void screen(@Nullable
                   java.lang.String category,
                   @Nullable
                   java.lang.String name,
                   @Nullable
                   Properties properties,
                   @Nullable
                   Options options)

The screen methods let your record whenever a user sees a screen of your mobile app, and attach a name, category or properties to the screen. Either category or name must be provided.

Parameters:

category - A category to describe the screen. Deprecated.

name - A name for the screen.

properties - Properties to add extra information to this call.

options - To configure the call.

See Also:

Screen Documentation

alias

public void alias(@NonNull
                  java.lang.String newId)

See Also:

alias(String, Options)

alias

public void alias(@NonNull
                  java.lang.String newId,
                  @Nullable
                  Options options)

The alias method is used to merge two user identities, effectively connecting two sets of user data as one. This is an advanced method, but it is required to manage user identities successfully in some of our integrations.

Usage:

 
   analytics.track("user did something");
   analytics.alias(newId);
   analytics.identify(newId);
  

Parameters:

newId - The new ID you want to alias the existing ID to. The existing ID will be either the previousId if you have called identify, or the anonymous ID.

options - To configure the call

Throws:

java.lang.IllegalArgumentException - if newId is null or empty

See Also:

Alias Documentation

flush

public void flush()

Asynchronously flushes all messages in the queue to the server, and tells bundled integrations to do the same.

getAnalyticsContext

public AnalyticsContext getAnalyticsContext()

Get the AnalyticsContext used by this instance.

getSnapshot

public StatsSnapshot getSnapshot()

Creates a StatsSnapshot of the current stats for this instance.

getApplication

public android.app.Application getApplication()

Return the Application used to create this instance.

getLogLevel

@Deprecated
public Analytics.LogLevel getLogLevel()

Deprecated. This will be removed in a future release.

Return the Analytics.LogLevel for this instance.

getLogger

public Logger getLogger()

Deprecated. This will be removed in a future release.

Return the Logger instance used by this client.

logger

public Logger logger(java.lang.String tag)

Return a new Logger with the given sub-tag.

logout

@Deprecated
public void logout()

Deprecated. Use reset() instead

Logs out the current user by clearing any information, including traits and user id.

reset

public void reset()

Resets the analytics client by clearing any stored information about the user. Events queued on disk are not cleared, and will be uploaded at a later time. Preserves BUILD and VERSION values.

optOut

public void optOut(boolean optOut)

Set the opt-out status for the current device and analytics client combination. This flag is persisted across device reboots, so you can simply call this once during your application (such as in a screen where a user can opt out of analytics tracking).

onIntegrationReady

public <T> void onIntegrationReady(java.lang.String key,
                                   Analytics.Callback<T> callback)

Register to be notified when a bundled integration is ready.

In most cases, integrations would have already been initialized, and the callback will be invoked fairly quickly. However there may be a latency the first time the app is launched, and we don't have settings for bundled integrations yet. This is compounded if the user is offline on the first run.

You can only register for one callback per integration at a time, and passing in a callback will remove the previous callback for that integration.

Usage:

 
   analytics.onIntegrationReady("Amplitude", new Callback() {
      @Override public void onIntegrationReady(Object instance) {
       Amplitude.enableLocationListening();
     }
   });
   analytics.onIntegrationReady("Mixpanel", new Callback<>() {
      @Override public void onIntegrationReady(MixpanelAPI mixpanel) {
       mixpanel.clearSuperProperties();
     }
   })*
  

onIntegrationReady

public void onIntegrationReady(Analytics.BundledIntegration integration,
                               Analytics.Callback callback)

Deprecated. Use onIntegrationReady(String, Callback) instead.

shutdown

public void shutdown()

Stops this instance from accepting further requests. In-flight events may not be uploaded right away.