Use Google Tag Manager
If you are using Firebase to track events such as screenviews or transactions, you can trigger these events for Contentsquare with minimal effort, thanks to Google Tag Manager.
Prerequisite
Section titled PrerequisiteIf you are following this Google Tag Manager integration process, you should already have followed the Google Tag Manager + Firebase setup as described in Google’s Tag Manager + Firebase: Getting Started
You also need to integrate the Contentsquare SDK see section: Add Contentsquare to your app.
Screenview events
Section titled Screenview eventsThis section covers how to trigger a Contentsquare screenview event for every Firebase screenview event. Firebase allows you to log screenviews automatically or manually for an exhaustive coverage of your app screens.
Variables
Section titled VariablesContentsquare screenview events require a name
parameter.
Firebase has 2 ways to track screens:
1. Variable for automatically tracked screens
Section titled 1. Variable for automatically tracked screensFirebase’s screen_view
events have an _sc
parameter (for screen class) which we can use as parameter for screens that are automatically tracked.
We will create a variable called Automatic Screenview Name with:
- The Variable Type set to Event Parameter
- The Event Type set to Custom Parameter
- The Event Parameter Key set manually to
_sc
2. Variable for manually tracked screens
Section titled 2. Variable for manually tracked screensFirebase’s screen_view
events have a _sn
parameter (for screen name) which we can use as parameter for screens that are manually tracked.
We will create a variable called Manual Screenview Name with:
- The Variable Type set to Event Parameter
- The Event Type set to Custom Parameter
- The Event Parameter Key set manually to
_sn
We can also create variables for our own custom parameters, for example, we can send a screen_view
event like this:
Analytics.logEvent(AnalyticsEventScreenView, parameters: [ AnalyticsParameterScreenName: "MyScreenName", "is_user_logged_in": "true"])
and create a variable called Is User Logged In with:
- The Variable Type set to Event Parameter
- The Event Type set to Custom Parameter
- The Event Parameter Key set manually to
is_user_logged_in
Check out Configure variables in Tag Manager for more information.
Screenview trigger
Section titled Screenview triggerWe will need to tell Google Tag Manager when to send a Contentsquare screenview, and for that we need to create a Trigger. Firebase sends screenviews as events of name screen_view
, so we need to create a trigger for that event.
- Name your trigger
Screenview Trigger
- Trigger Type should be set to Custom
- Trigger should fire on Some Events
- For the Event, the Event Name should be equal to
screen_view
Create the custom function Tag
Section titled Create the custom function TagIn Google Tag Manager, a Tag is what configures what happens when some trigger is activated. It will be automatically linked to a custom class which we will create in a later step.
The Tag Type should be a Function Call. You will also need to fill in the Class Name field with a class name of your liking, typically related to what the tag is about (here we chose ContentsquareScreenviewTag
), which you will re-use later.
Adding the trigger and the variables to the Tag
Section titled Adding the trigger and the variables to the TagEdit the ContentsquareScreenviewTag
Tag:
- Add an argument with the key
auto_screen_name
and the variable{{Automatic Screenview Name}}
as the value - Add an argument with the key
manual_screen_name
and the variables{{Manual Screenview Name}} | {{Is User Logged In}}
or{{Manual Screenview Name}}
as the value - Add Contentsquare Screenview Trigger as the Tag’s trigger
It should look like this now:
Create the custom function Tag class
Section titled Create the custom function Tag classIn your app code, create a class of the same name as the Class Name
you configured in the GTM interface, for example ContentsquareScreenviewTag
. This is how GTM connects the configuration and the actual class to trigger. This class is used to call the Contentsquare screenview tracking function as follows:
@objc(ContentsquareScreenviewTag)final class ContentsquareScreenviewTag: NSObject, TAGCustomFunction { @objc func execute(withParameters parameters: [AnyHashable : Any]!) -> NSObject! { let autoScreenName = parameters[AnyHashable("auto_screen_name")] as? String let manualScreenName = parameters[AnyHashable("manual_screen_name")] as? String let screenName = manualScreenName ?? autoScreenName ?? "No screen name!" Contentsquare.send(screenViewWithName: screenName) return nil }}
@implementation ContentsquareScreenviewTag <TAGCustomFunction>
- (NSObject*)executeWithParameters:(NSDictionary*)parameters { NSString *autoScreenName = [parameters objectForKey:@"auto_screen_name"]; NSString *manualScreenName = [parameters objectForKey:@"manual_screen_name"]; NSString *screenName = manualScreenName ? : (autoScreenName ? : @"No screen name!"); [Contentsquare sendWithScreenViewWithName:screenName]; return nil; }
@end
Now, every time Firebase sends a screenview event, Contentsquare will send one as well.
Screenview events with Custom Variables
Section titled Screenview events with Custom VariablesIt is possible to send custom variables along with the screenview events.
To do so:
-
Follow Use Google Tag Manager > Screenview events
-
Add extra arguments to the
ContentsquareScreenviewTag
Tag as follows:- Key: the index of the custom variable
- Value: a string that will contain the custom variable name and value such as
CVAR_NAME : {{Event Name}}
It should look like this:
In the code of your application, edit the code of your class to handle the added custom variables:
@objc(ContentsquareScreenviewTag)final class ContentsquareScreenviewTag: NSObject, TAGCustomFunction { @objc func execute(withParameters parameters: [AnyHashable : Any]!) -> NSObject! { let autoScreenName = parameters[AnyHashable("auto_screen_name")] as? String let manualScreenName = parameters[AnyHashable("manual_screen_name")] as? String let screenName = manualScreenName ?? autoScreenName ?? "No screen name!" var cvars = [CustomVar]() for (gTagKey, gTagValue) in parameters {
guard let gTagKey = gTagKey as? String, let cvarIndex = UInt32(gTagKey), let gTagValue = gTagValue as? String else { continue }
let cvarKeyValue = gTagValue.components(separatedBy: ":") if cvarKeyValue.count == 2 { let name = cvarKeyValue[0].trimmingCharacters(in: .whitespaces) let value = cvarKeyValue[1].trimmingCharacters(in: .whitespaces) let cvar = CustomVar(index: cvarIndex, name: name, value: value) cvars.append(cvar) } } Contentsquare.send(screenViewWithName: screenName, cvars: [cvars]) return nil }}
@implementation ContentsquareScreenviewTag<TAGCustomFunction>
- (NSObject*)executeWithParameters:(NSDictionary*)parameters { NSString *autoScreenName = parameters[@"auto_screen_name"]; NSString *manualScreenName = parameters[@"manual_screen_name"]; NSString *screenName = manualScreenName ?: autoScreenName ?: @"No screen name!";
NSMutableArray *cvars = [NSMutableArray array]; for (NSString *gTagKey in parameters) {
NSUInteger cvarIndex = [gTagKey integerValue]; NSString *gTagValue = parameters[gTagKey]; NSArray *cvarKeyValue = [gTagValue componentsSeparatedByString:@":"];
if (cvarKeyValue.count == 2) { NSString *name = [cvarKeyValue[0] stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceCharacterSet]]; NSString *value = [cvarKeyValue[1] stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceCharacterSet]]; CustomVar *cvar = [[CustomVar alloc] initWithIndex:cvarIndex name:name value:value]; [cvars addObject:cvar]; } }
[Contentsquare sendScreenViewWithName:screenName cvars:cvars]; return nil;}@end
With this code, the custom variables will be sent by Contentsquare automatically along with the screenview.
Transaction events
Section titled Transaction eventsA Contentsquare transaction event can also be triggered for every Firebase ecommerce_purchase
event (See Firebase Objective-C/Swift documentation).
To do so, you will need to follow the setup described below.
Variables
Section titled VariablesWe have to create at least two variables in order to be able to build a transaction event, Value and Currency. Optionally, it is also possible to pass a transaction identifier, meaning you would need to create an additional variable in order to be able to use it.
Value (mandatory)
Section titled Value (mandatory)Currency (mandatory)
Section titled Currency (mandatory)Transaction ID (optional)
Section titled Transaction ID (optional)Trigger
Section titled TriggerCreate the following custom trigger.
Create a Function call Tag called ContentsquareTransactionTag
, pass the two to three variables created earlier as arguments (skip the id
line if you do not want to use it) and set its trigger to the one you just created.
Implementing the function call
Section titled Implementing the function callWe need to create a ContentsquareTransactionTag
class, and have it adhere to the TAGCustomFunction
protocol to link it to the Google Tag Manager custom Tag of the same name.
Take good note that in order to be able to create and send a Contentsquare Transaction successfully, when you create a Firebase purchase event you will have to at least pass values for kFIRParameterValue
and kFIRParameterCurrency
, and can optionally pass a value for kFIRParameterTransactionID
, when you create a Firebase purchase event.
@objc(ContentsquareTransactionTag)final class ContentsquareTransactionTag: NSObject, TAGCustomFunction {
@objc func execute(withParameters parameters: [AnyHashable : Any]!) -> NSObject! { if let currency = parameters[AnyHashable("currency")] as? String, let value = parameters[AnyHashable("value")] as? Float { let identifier = parameters[AnyHashable("id")] as? String Contentsquare.send(transaction: CustomerTransaction.init(id: identifier, value: value, currency: currency)) } return nil }}
@implementation ContentsquareTransactionTag <TAGCustomFunction>
- (NSObject*)executeWithParameters:(NSDictionary*)parameters { NSString *identifier = [parameters objectForKey:@"transaction_id"]; NSNumber *value = [parameters objectForKey:@"value"]; NSString * currency = [parameters objectForKey:@"currency"]; if (currency && value) { [Contentsquare sendWithTransaction:[[CustomerTransaction alloc] initWithId:identifier value:[value floatValue] stringCurrency:currency]]; } return nil;}
@end
Now, every time Firebase sends an ecommerce_purchase
event, Contentsquare will send one as well.
Dynamic variable events
Section titled Dynamic variable eventsWe can send values from any Firebase event as a Contentsquare dynamic variable:
Analytics.logEvent("addToCart", parameters: [ "product_count": 12, "product_name": "ProductA"])
Variables
Section titled VariablesThe addToCart
event has parameters product_count
, product_name
, we will create variables called Product Count and Product Name with:
- The Variable Type set to Event Parameter
- The Event Type set to Custom Parameter
- The Event Parameter Key set manually to
product_count
/product_name
Check out Configure variables in Tag Manager for more information.
Triggers
Section titled TriggersWe need to create a Trigger to tell Google Tag Manager when to send a Contentsquare dynamic variable, so we will create one for the event addToCart
.
- Name your trigger
AddToCartTrigger
- Trigger Type should be set to Custom
- Trigger should fire on Some Events
- For the Event, the Event Name should be equal to
addToCart
Create the custom function Tag
Section titled Create the custom function TagWe need to create a function tag AddToCartDynamicVar
- The Tag Type set to Function Call
- The Class Name set to DynamicVarTag (we’ll create this class later)
- Add two arguments,
Key: cs_dynamic_var_key, Value: Product
,Key: cs_dynamic_var_value, Value: {{Product Name}}: {{Product Count}}
- The Triggering set to AddToCartTrigger
It should look like this now:
Create the custom function Tag class
Section titled Create the custom function Tag classIn your app code, create a class named DynamicVarTag
, assuming you used the name we suggested when creating the Tag in the GTM interface. If you named it otherwise, make sure to use the same name here, as it is how GTM connects the configuration and the actual class to trigger. We will use this class to call the Contentsquare dynamic variable function as follows.
import GoogleTagManagerimport ContentsquareModule
@objc(DynamicVarTag)final class DynamicVarTag: NSObject, TAGCustomFunction { @objc func execute(withParameters parameters: [AnyHashable : Any]!) -> NSObject! { guard let dynamicVarKey = parameters["cs_dynamic_var_key"] as? String else { return nil } let dynamicVarValue = parameters["cs_dynamic_var_value"]
if let dynamicVarStringValue = dynamicVarValue as? String { let dynamicVarString = DynamicVar(key: dynamicVarKey, value: dynamicVarStringValue) Contentsquare.send(dynamicVar: dynamicVarString) } else if let dynamicVarIntValue = dynamicVarValue as? UInt32 { let dynamicVarInt = DynamicVar(key: dynamicVarKey, value: dynamicVarIntValue) Contentsquare.send(dynamicVar: dynamicVarInt) } return nil }}
Now, every time Firebase sends a addToCart
event, Contentsquare will send a dynamic variable DynamicVar(key: "Product", value: "ProductA: 12")
.