The Tealium Xamarin integration provides a set of cross-platform interfaces and configuration classes that interface with the native Tealium iOS and Android SDKs to simplify Tealium tracking Xamarin developers.
In this article:
Table of Contents Placeholder
Overview
The Tealium Xamarin integration provides a set of cross-platform interfaces and configuration classes that interface with our native iOS and Android SDKs to make Tealium tracking more straightforward for Xamarin developers.
DLLs and Lifecycle Modules
Dynamic-Link Libraries (DLLs) described in this article are available at: https://github.com/Tealium/tealium-xamarin.
Available DLLs
Several DLLs are available for the Xamarin integration:
Tealium.Common.dll This DLL contains cross-platform code, interfaces, and common code to be used in all projects within your Xamarin application. Add this DLL as a reference in both shared project and platform-specific projects.
Abstraction DLLs Abstraction DLLS are included to create an easy-to-use C# API wrapper for the native Tealium SDKs and should only be referenced in platform-specific projects. These libraries contain platform-specific, concrete class implementations for the interfaces and abstract classes provided by the Tealium common library. You can code all of your cross-platform logic against the common library.
Tealium.Droid.dll – for Android mobile platforms
Tealium.iOS.dll – for Apple mobile platforms
There are DLLs specific to each mobile platform which are referenced by the abstraction DLLs. The platform DLLs are binding libraries and therefore embed our the native SDKs - they provide auto-generated wrapper code that would allow you to interact with our native SDKs directly and as a result they can be used standalone if desired.
Tealium.Platform.Droid.dll
Tealium.Platform.iOS.dll
Binding libraries can be used by themselves. The fact that they are automatically generated results in vastly different namespaces for each platform, which adds an extra complication to development efforts. It is advised to make use of the Common and platform-specific abstraction libraries instead.
Lifecycle Modules
An optional lifecycle module is available by referencing the relevant DLL for the platform. These are binding libraries for the native equivalent SDKs:
Tealium.Platform.Lifecycle.Droid.dll
Tealium.Platform.Lifecycle.iOS.dll
Android Shared Project Example
The following example illustrates the Shared project and Android platform-specific project from a typical Xamarin based app:
As shown in the example, the Shared Project references only the Tealium.Common.dll library, whereas the Android-specific project references all of the following:
Tealium.Common.dll
Tealium.Droid.dll
Tealium.Platform.Droid.dll
Tealium.Platform.Lifecycle.Droid.dll
Basic Configuration
The first step for initialization is to ensure that your projects reference the appropriate libraries as described in the Overview. Though not required, Tealium recommends using the TealiumInstanceManager classes provided as they provide out-of-the-box, thread-safe Tealium instance management.
Android Example
The following example applies to an Android project:
using Tealium.Droid; //... ITealiumInstanceManager instanceManager = new TealiumInstanceManager(new TealiumInstanceFactoryDroid(<myAndroidApplication>)); //Optional Lifecycle Module enablement - ensure to reference Tealium.Platform.Lifecycle.Droid.dll TealiumLifecycleManager.SetLifecycleAutoTracking = TealiumDroid.Lifecycle.TealiumLifecycleControlDelegation.SetLifecycleAutoTracking;
iOS Example
The following example applies to an Apple project:
using Tealium.iOS; //... ITealiumInstanceManager instanceManager = new TealiumInstanceManager(new TealiumInstanceFactoryIOS()); //Optional Lifecycle Module enablement - ensure to reference Tealium.Platform.Lifecycle.iOS.dll TealiumLifecycleManager.SetLifecycleAutoTracking = TealiumIOS.Lifecycle.TealiumLifecycleControlDelegation.SetLifecycleAutoTracking;
Creating Instances
Once the TealiumInstanceManager is created, you can begin creating Tealium instances as with the native SDKs. The TealiumInstanceManager is a multiton pattern that provides access to multiple named instances if you need to track data on more than a Tealium profile.
Use the following steps to create a new instance:
Create a TealiumConfig object to hold various required and optional configuration items, as shown in the following example:
TealiumConfig tealConfig = new TealiumConfig("TEALIUM_INSTANCE",//Instance Name "tealiummobile",//Tealium Account Name "demo",//Tealium Profile Name "dev",//Tealium Envrionment true);//Optional Auto Lifecycle AutoTracking (default: true)
When complete, you can then can use your TealiumInstanceManager to create a Tealium instance which can be used to track your events, as shown in the following example:
ITealium tealium = instanceManager . CreateInstance (tealC onfig );
Advanced Configuration
The TealiumConfig class has constructor options that allow you to specify optional parameters to enable or disable the more advanced aspects of the Tealium Mobile SDKs. These parameters are optional as not all customers require these features.
Remote Commands
An object containing RemoteCommand blocks if you need to work with the features provided by the TagBridge tag. Similarly, you can supply code for the delegated methods that you can use in the native versions of the SDKs as well, such as Remote Commands.
While the majority of the events within mobile are either sent to our data collection servers to be actioned through connectors, or processed in the tag management web view to trigger vendor tags. Remote Commands provide additional flexibility in that events used for tag management can pass data back to your native code through the IRemoteCommand interface.
The following sample code prints out the CommandId (set to TealiumConsts.REMOTE_COMMAND_ID ). Using this example, you will also have access to a full payload of data, as configured in the associated TagBridge Custom Command tag required to set this up:
static List<IRemoteCommand> SetupRemoteCommands() { var command = new DelegateRemoteCommand(TealiumConsts.REMOTE_COMMAND_ID, "Test command " + TealiumConsts.REMOTE_COMMAND_ID) { HandleResponseDelegate = (DelegateRemoteCommand cmd, IRemoteCommandResponse resp) => { System.Diagnostics.Debug.WriteLine($"Handling command {cmd.CommandId}..."); } }; return new List<IRemoteCommand>() { command }; }
Delegate Methods
There are five delegated methods that allow you to inject code into the processing logic within the Tealium SDK:
DelegateDispatchValidator Provides two delegate methods where the Boolean return value determines whether or not an existing dispatch should be dropped or queued. This is useful if you have steps within your app where you know that the user may be offline or you specifically want to write your own batching logic for example.
ShouldDropDispatchDelegate
ShouldQueueDispatchDelegate
DispatchSentDelegateEventListener Called whenever a dispatch has been sent.
DispatchQueuedDelegateEventListener Called whenever a dispatch has been queued.
WebViewReadyDelegateEventListener Called when the WebView is fully loaded and ready, if you are using the Tag Management module.
SettingsPublishedDelegateEventListener Executed when there has been an updated set of publish settings retrieved.
The following example illustrates the usage of the delegate method:
static TealiumAdvancedConfig SetupAdvancedConfig() { DelegateDispatchValidator validator = new DelegateDispatchValidator() { ShouldDropDispatchDelegate = (ITealium arg1, IDispatch arg2) => { System.Diagnostics.Debug.WriteLine("Inside ShouldDropDispatchDelegate!"); return false; }, ShouldQueueDispatchDelegate = (ITealium arg1, IDispatch arg2, bool shouldQueue) => { System.Diagnostics.Debug.WriteLine("Inside ShouldQueueDispatchDelegate!"); return shouldQueue; } }; DispatchSentDelegateEventListener sendingListener = new DispatchSentDelegateEventListener() { DispatchSent = (tealium, dispatch) => { System.Diagnostics.Debug.WriteLine("Inside DispatchSent!"); dispatch.PutString("KeyAddedBySendListener", "Value added by sending listener."); } }; DispatchQueuedDelegateEventListener queuingListener = new DispatchQueuedDelegateEventListener() { DispatchQueued = (tealium, dispatch) => { System.Diagnostics.Debug.WriteLine("Inside DispatchQueued!"); dispatch.PutString("KeyAddedByQueuedListener", "Value added by queuing listener."); } }; WebViewReadyDelegateEventListener webViewListener = new WebViewReadyDelegateEventListener() { WebViewReady = (tealium, webView) => { System.Diagnostics.Debug.WriteLine("Inside WebViewReady!"); } }; SettingsPublishedDelegateEventListener settingsListener = new SettingsPublishedDelegateEventListener() { SettingsPublished = (tealium) => { System.Diagnostics.Debug.WriteLine("Inside SettingsPublished!"); } }; TealiumAdvancedConfig advConfig = new TealiumAdvancedConfig(validator, sendingListener, queuingListener, webViewListener, settingsListener); return advConfig; }
Tracking
To trigger specific events within your app, use the appropriate method for the type of event that you want to track, as shown in the following sections.
Screen View Tracking
The following example uses screen view tracking:
// Get ITealium instance ITealium tealium = instanceManager . GetExistingInstance ( TealiumConsts . INSTANCE_ID ); // Track a Page View event with the title "View Name" but no extra event data. tealium . TrackView ( " View Name " ); // Track a Page View event with the title "View Name" along with the "page_type" event daata. tealium . TrackView ( " View Name " , new Dictionary < String , object >( 1 ){ { " page_type " , " product detail page " } }); // Track a Page View event with the title "View Name" along with a single piece of event data. // This an equivalent way to the track call directly above. tealium . TrackView ( " View Name " , " page_type " , " product detail page " );
Event Tracking
The following example uses event tracking:
// Get ITealium instance ITealium tealium = instanceManager.GetExistingInstance(TealiumConsts.INSTANCE_ID); // The TrackEvent method has the same overloads as TrackView, so only one additional example is provided. // Track an Event with three pieces of specific Event Data. tealium.TrackEvent("Event Name", new Dictionary<String, object>(3){ {"event_category", "Menu"}, {"event_action", "Button Click"}, {"event_label", "Logo"} });
Adding Event Data
As with the native SDKs, there are two additional types of variables that you can set to be added to each of your events.
Persistent Data Persistent data will be merged into your event-specific data dictionary on every event that you trigger, as well as persist between launches, as shown in the following example:
//Get ITealium instance ITealium tealium = instanceManager.GetExistingInstance(TealiumConsts.INSTANCE_ID); tealium.AddPersistentDataSources(new Dictionary<string, object>(1) { //Data will be merged into every event. { "PersistentDataTest", "Example persistent value." } });
Volatile Data Volatile data will be merged into your event-specific data dictionary on every event, just like persistent data. The key difference is that once the application is closed, volatile data is lost and will not be present on the next launch.
//Get ITealium instance ITealium tealium = instanceManager.GetExistingInstance(TealiumConsts.INSTANCE_ID); tealium . AddVolatileDataSources ( new Dictionary < string , object >( 1 )
{
//Data will be merged into every event.
{ " VolatileDataTest " , " Example volatile value. " }
});
Consent Management
The Consent Management feature comes from the two native SDKs embedded into the DLLs named Tealium.Platform.*.dlls . The Tealium.Common.dll provides the following category and status enums to use:
Tealium.ConsentManager.ConsentStatus
Tealium.ConsentManager.ConsentCategory
Enabling Consent Management
To enable Consent Management, simply pass the optional parameter in the constructor of TealiumConfig or set it as a property, as shown in the following example:
TealiumConfig tealC onfig = new TealiumConfig ( TealiumConsts . INSTANCE_ID ,
TealiumConsts . ACCOUNT_NAME ,
TealiumConsts . PROFILE_NAME ,
TealiumConsts . ENVIRONMENT ,
true ,
commands ,
advConfig ,
false ); //optional Consent Manager Enablement.
//or subsequently enable it:
tealConfig . IsConsentManagerEnabled = true ;
//then initialise your Tealium Instance:
var tealium = instanceManager . CreateInstance (tealC onfig );
Overriding Initial Consent Status
As with the native SDKs for both Android and iOS, when Consent Management is enabled, new users are assumed to be in an Unknown state. Tracking requests are queued up until the consent status has been opted-in or out, at which point events will be sent or purged, respectively.
You can override the initial status through properties on the TealiumConfig object, as shown in the following example:
// enable Consent Manager:
tealConfig . IsConsentManagerEnabled = true ;
// Set Users to be Consented by default:
tealConfig. InitialUserConsentStatus = ConsentManager . ConsentStatus . Consented ;
// Or set Users to be Not Consented by default:
tealConfig. InitialUserConsentStatus = ConsentManager . ConsentStatus . NotConsented ;
// Opt users into All Categories
tealConfig. InitialUserConsentCategories = ConsentManager . AllCategories ;
// or none:
tealConfig. InitialUserConsentCategories = ConsentManager . NoCategories ;
// or partial opt-in, only to Analytics and Mobile categories.
tealConfig. InitialUserConsentCategories = new ConsentCategory []{
ConsentManager . ConsentCategory . Analytics ,
ConsentManager . ConsentCategory . Mobile
};
Updating the User Consent Selection
The ConsentManager can be interacted with directly from the Tealium instance, through the ConsentManager property.
If you need to update a user's consent selection, simply pass the relevant values. Only the enum values available in the ConsentManager.ConsentCategory and ConsentManager.ConsentStatus should be used, as shown in the following example:
// if the user is in an Unknown state, then the following code would trigger any queued events would be sent after this:
ITealium tealium = instanceManager . GetExistingInstance ( TealiumConsts . INSTANCE_ID );
tealium . ConsentManager . UserConsentStatus = ConsentManager . ConsentStatus . Consented ;
// The above will inherently opt the user into all categories as none have been provide.
// To grant consent and opt into a subset of categories you can use the overload:
tealium . ConsentManager . UserConsentStatusWithCategories ( ConsentManager . ConsentStatus . Consented , new ConsentCategory []{
ConsentManager . ConsentCategory . Analytics
});
Resetting Consent Preferences
Additional options area available to reset the currently selected consent preferences. This will revert the user back to an Unknown status so that subsequent events will begin being queued again.
To completely disable, disable it on the TealiumConfig object, as shown in the following example:
ITealium tealium = instanceManager . GetExistingInstance ( TealiumConsts . INSTANCE_ID );
tealium . ConsentManager . ResetUserConsentPreferences ();
Resources
The following sections provide links to Tealium and Xamarin resources that contain detailed information about Tealium for iOS and Android
Tealium Documentation
The following resources provide links to Tealium documentation for Android and iOS. If you are building a mobile application in Xamarin, you will use bindings to our iOS and Android libraries.
Tealium for iOS
Tealium for Android
Alternatively, if only using UDH services (AudienceStream, EventStream, DataAccess), the Tealium C# library may be used as the native code in a Xamarin project.
Vendor Documentation
The following resources provide links to Xamarin's extensive documentation for adding Tealium's Android and iOS libraries:
Xamarin
Binding a Java Library
Xamarin - Binding an iOS Objective-C Library
Walkthrough: Binding an iOS Objective-C Library
... View more