com.snowplowanalytics.snowplow

Class Snowplow

java.lang.Object

com.snowplowanalytics.snowplow.Snowplow

public class Snowplow
extends Object

Entry point to instance a new Snowplow tracker.

Constructor Summary

Constructors

Constructor and Description
Snowplow()

Method Summary

Modifier and Type	Method and Description
static TrackerController	createTracker(Context context, String namespace, NetworkConfiguration network, Configuration... configurations) Create a new tracker instance which will be used inside the app to track events.
static TrackerController	createTracker(Context context, String namespace, String endpoint, HttpMethod method) Create a new tracker instance which will be used inside the app to track events.
static TrackerController	getDefaultTracker() The default tracker instance is the first created in the app, but that can be overridden programmatically calling setTrackerAsDefault(TrackerController).
static Set<String>	getInstancedTrackerNamespaces()
static TrackerController	getTracker(String namespace) Using the namespace identifier is possible to get the trackerController if already instanced.
static void	refresh(Context context, androidx.core.util.Consumer<List<String>> onSuccess) Reconfigure, create or delete the trackers based on the configuration downloaded remotely.
static void	removeAllTrackers() Remove all the trackers.
static boolean	removeTracker(TrackerController trackerController) A tracker can be removed from the active trackers of the app.
static boolean	setTrackerAsDefault(TrackerController trackerController) Set the passed tracker as default tracker if it's registered as an active tracker in the app.
static void	setup(Context context, RemoteConfiguration remoteConfiguration, List<com.snowplowanalytics.snowplow.internal.remoteconfiguration.ConfigurationBundle> defaultBundles, androidx.core.util.Consumer<List<String>> onSuccess) Setup a single or a set of tracker instances which will be used inside the app to track events.

Methods inherited from class java.lang.Object

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

Constructor Detail

Snowplow

public Snowplow()

Method Detail

setup

public static void setup(@NonNull
                         Context context,
                         @NonNull
                         RemoteConfiguration remoteConfiguration,
                         @Nullable
                         List<com.snowplowanalytics.snowplow.internal.remoteconfiguration.ConfigurationBundle> defaultBundles,
                         @Nullable
                         androidx.core.util.Consumer<List<String>> onSuccess)

Setup a single or a set of tracker instances which will be used inside the app to track events. The app can run multiple tracker instances which will be identified by string `namespaces`. The trackers configuration is automatically download from the endpoint indicated in the `RemoteConfiguration` passed as argument. For more details see `RemoteConfiguration`. The method is asynchronous and you can receive the list of the created trackers in the callbacks once the trackers are created. The callback can be called multiple times in case a cached configuration is ready and later a fetched configuration is available. You can also pass as argument a default configuration in case there isn't a cached configuration and it's not able to download a new one. The downloaded configuration updates the cached one only if the configuration version is greater than the cached one. Otherwise the cached one is kept and the callback is not called. IMPORTANT: The EventStore will persist all the events that have been tracked but not yet sent. Those events are attached to the namespace. If the tracker is removed or the app relaunched with a different namespace, those events can't be sent to the collector and they remain in a zombie state inside the EventStore. To remove all the zombie events you can an internal method `removeUnsentEventsExceptForNamespaces` on `SPSQLEventStore` which will delete all the EventStores instanced with namespaces not listed in the passed list.

Parameters:

context - The Android app context.

remoteConfiguration - The remote configuration used to indicate where to download the configuration from.

defaultBundles - The default configuration passed by default in case there isn't a cached version and it's able to download a new one.

onSuccess - The callback called when a configuration (cached or downloaded) is set It passes the list of the namespaces associated to the created trackers.

refresh

public static void refresh(@NonNull
                           Context context,
                           @Nullable
                           androidx.core.util.Consumer<List<String>> onSuccess)

Reconfigure, create or delete the trackers based on the configuration downloaded remotely. The trackers configuration is automatically download from the endpoint indicated in the `RemoteConfiguration` previously used to setup the trackers. The method is asynchronous and you can receive the list of the created trackers in the callbacks once the trackers are created. The downloaded configuration updates the cached one only if the configuration version is greater than the cached one. Otherwise the cached one is kept and the callback is not called. IMPORTANT: The EventStore will persist all the events that have been tracked but not yet sent. Those events are attached to the namespace. If the tracker is removed or the app relaunched with a different namespace, those events can't be sent to the collector and they remain in a zombie state inside the EventStore. To remove all the zombie events you can an internal method `removeUnsentEventsExceptForNamespaces` on `SPSQLEventStore` which will delete all the EventStores instanced with namespaces not listed in the passed list.

Parameters:

context - The Android app context.

onSuccess - The callback called when a configuration (cached or downloaded) is set It passes the list of the namespaces associated to the created trackers.

createTracker

@NonNull
public static TrackerController createTracker(@NonNull
                                                       Context context,
                                                       @NonNull
                                                       String namespace,
                                                       @NonNull
                                                       String endpoint,
                                                       @NonNull
                                                       HttpMethod method)

Create a new tracker instance which will be used inside the app to track events. The app can run multiple tracker instances which will be identified by string `namespaces`. The tracker will be configured with default setting and only the collector endpoint URL need to be passed for the configuration. For the default configuration of the tracker see TrackerConfiguration(String) To configure tracker with more details see createTracker(Context, String, NetworkConfiguration, Configuration...) To use the tracker as singleton see getDefaultTracker()

Parameters:

context - The Android app context.

namespace - The namespace used to identify the current tracker among the possible multiple tracker instances.

endpoint - The URL of the collector.

method - The method for the requests to the collector (GET or POST).

Returns:

The tracker instance created.

createTracker

@NonNull
public static TrackerController createTracker(@NonNull
                                                       Context context,
                                                       @NonNull
                                                       String namespace,
                                                       @NonNull
                                                       NetworkConfiguration network,
                                                       @NonNull
                                                       Configuration... configurations)

Create a new tracker instance which will be used inside the app to track events. The app can run multiple tracker instances which will be identified by string `namespaces`. Each tracker can be configured by various configuration objects implementing the Configuration interface. For the default configuration of the tracker see TrackerConfiguration(String) The configurations are only for the setup of the tracker and *any change to the configuration object properties will NOT change the tracker setup at runtime*. To use the tracker as singleton see getDefaultTracker()

Parameters:

context - The Android app context.

namespace - The namespace used to identify the current tracker among the possible multiple tracker instances.

network - The NetworkConfiguration object with settings for the communication with the collector.

configurations - All the configuration objects with the details about the fine tuning of the tracker.

Returns:

The tracker instance created.

getDefaultTracker

@Nullable
public static TrackerController getDefaultTracker()

The default tracker instance is the first created in the app, but that can be overridden programmatically calling setTrackerAsDefault(TrackerController).

Returns:

The default tracker instance or `null` whether the tracker has been removed or never initialized.

getTracker

@Nullable
public static TrackerController getTracker(@NonNull
                                                     String namespace)

Using the namespace identifier is possible to get the trackerController if already instanced.

Parameters:

namespace - The namespace that identifies the tracker.

Returns:

The tracker if it exist with that namespace.

setTrackerAsDefault

public static boolean setTrackerAsDefault(@NonNull
                                          TrackerController trackerController)

Set the passed tracker as default tracker if it's registered as an active tracker in the app. If the passed instance is of a tracker which is already removed (see removeTracker) then it can't become the new default tracker and the operation fails.

Parameters:

trackerController - The new default tracker.

Returns:

Whether the tracker passed is registered among the active trackers of the app.

removeTracker

public static boolean removeTracker(@NonNull
                                    TrackerController trackerController)

A tracker can be removed from the active trackers of the app. Once it has been removed it can't be added again or set as default. The unique way to resume a removed tracker is creating a new tracker with same namespace and same configurations. The removed tracker is always stopped.

Parameters:

trackerController - The tracker controller to remove.

Returns:

Whether it has been able to remove it.

removeAllTrackers

public static void removeAllTrackers()

Remove all the trackers. The removed tracker is always stopped.

See Also:

removeTracker(TrackerController)

getInstancedTrackerNamespaces

@NonNull
public static Set<String> getInstancedTrackerNamespaces()

Returns:

Set of namespace of the active trackers in the app.