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
static interface	Analytics.Callback 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) The alias method is used to merge two user identities, effectively connecting two sets of user data as one.
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.
Log	getLogger() Return the Log instance used by this client.
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) The group method lets you associate a user with a group.
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) Identify lets you tie one of your users and their actions to a recognizable 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) Identify lets you tie one of your users and their actions to a recognizable userId.
void	logout() Deprecated. Use reset() instead
void	onIntegrationReady(Analytics.BundledIntegration bundledIntegration, Analytics.Callback callback) Register to be notified when a bundled integration is ready.
void	reset() Resets the analytics client by clearing any stored information about the user.
void	screen(java.lang.String category, java.lang.String name)
void	screen(java.lang.String category, java.lang.String name, Properties properties)
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) The track method is how you record any actions your users perform.
void	track(java.lang.String event, Properties properties) The track method is how you record any actions your users perform.
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(java.lang.String userId)

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. This method will simply set the userId for the current user.

See Also:

identify(String, Traits, Options)

identify

public void identify(Traits traits)

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. This method will simply add the given traits to the user profile.

See Also:

identify(String, Traits, Options)

identify

public 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. 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(java.lang.String groupId)

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.

See Also:

group(String, Traits, Options)

group

public void group(java.lang.String groupId,
                  Traits groupTraits,
                  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(java.lang.String event)

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.

See Also:

track(String, Properties, Options)

track

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

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.

See Also:

track(String, Properties, Options)

track

public void track(java.lang.String event,
                  Properties properties,
                  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(java.lang.String category,
                   java.lang.String name)

See Also:

screen(String, String, Properties, Options)

screen

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

See Also:

screen(String, String, Properties, Options)

screen

public 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.

Either category or name must be provided.

Parameters:

category - A category to describe the screen

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(java.lang.String newId)

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.

See Also:

alias(String, Options)

alias

public 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. 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 Log getLogger()

Return the Log instance used by this client.

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.

shutdown

public void shutdown()

Stops this instance from accepting further requests.

onIntegrationReady

public void onIntegrationReady(Analytics.BundledIntegration bundledIntegration,
                               Analytics.Callback 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.

The callback is invoked on the same thread we call integrations on, so if you want to update the UI, make sure you move off to the main thread.

Usage:

 
   analytics.onIntegrationReady(BundledIntegration.AMPLITUDE, new Callback() {
      @Override public void onIntegrationReady(Object instance) {
       Amplitude.enableLocationListening();
     }
   });
   analytics.onIntegrationReady(BundledIntegration.MIXPANEL, new Callback() {
      @Override public void onIntegrationReady(Object instance) {
       ((MixpanelAPI) instance).clearSuperProperties();
     }
   })*