Overview
A class that is the mobile implementation of Google Tag Manager (GTM).
Sample usage:
TAGContainer *container =
[[TAGManager instance] openContainerById:myContainerId];
NSString *value = [container stringForKey:@"myKey"];TAGDataLayer *dataLayer = [[TAGManager instance] dataLayer]; [dataLayer push:@{@"event": @"openScreen", @"screenName": @"Main Page"}];
A container is a collection of macros, rules, and tags. It is created within the GTM application (http://www.google.com/tagmanager), and is assigned a container ID. This container ID is the one used within this API.
The TAGContainer class provides methods for retrieving macro values given the macro name. The routines booleanForKey: (TAGContainer), doubleForKey: (TAGContainer), int64ForKey: (TAGContainer), stringForKey: (TAGContainer) return the current value for the value collection macro name, depending on the rules associated with that macro in the container.
As an example, if your container has a value collection macro with a key "speed" whose value is 32, and the enabling rule is Language is "en"; and another value collection macro with a key "speed" whose value is 45, and the enabling rule is Language is not "en", then making the following call:
[container longForKey:@"speed"]
will return either 32 if the current language of the device is English, or 45 otherwise.
The data layer is a map holding generic information about the application. The TAGDataLayer class provides methods to push and retrieve data from the data layer. Pushing an event key to the data layer will cause tags that match this event to fire.
An initial version of the container is bundled with the application. It should be placed as a resource in the bundle with name containerId where containerId is the same container ID you will use within this API. When you call openContainerById:callback: (TAGManager), the container will be returned with those bundled rules/tags/macros. You will create the container in the UI and use the Download button to download it.
You can modify the container in the UI and publish a new version. In that case, the next time the mobile app refreshes the container from the network (currently every 12 hours), it will get that new version. When you call one of the get... routines, the value will be computed using the most recent rules.
The downloaded container is saved locally. When you call openContainerById:callback: (TAGManager), it will first load the default container, and will then asynchronously load any saved container. If none is found or if it is older than 12 hours, it will try to retrieve a newer version from the network. You can find the status of those asynchronous loads by passing a TAGContainerCallback to openContainerById:callback: (TAGManager).
Sometimes you may want to block until either a non-default container is available, or until a recent fresh container is available. You can do that by using the callbacks in openContainerById:callback: (TAGManager) or use TAGContainerOpener.
When you are finished with a container, call close (TAGContainer).
Public Member Functions | |
| (TAGContainer *) | - openContainerById:callback: |
| Returns a container. | |
| (TAGContainer *) | - getContainerById: |
Returns the container associated with the given containerId; returns nil if the container is not already open. | |
| (BOOL) | - previewWithUrl: |
| Previews the app with the input url. | |
| (void) | - dispatch |
| Dispatches any pending network traffic generated by tags (arbitrary pixels, analytics beacons, etc). | |
| (void) | - dispatchWithCompletionHandler: |
| Dispatches the next pending network traffic in the queue, calling completionHandler when the request has either been sent (returning kTAGDispatchGood) or an error has resulted (returning kTAGDispatchError). | |
Static Public Member Functions | |
| (TAGManager *) | + instance |
| Gets the singleton instance of the TAGManager class, creating it if necessary. | |
Properties | |
| id< TAGLogger > | logger |
| The logger to use for Google Tag Manager SDK. | |
| TAGRefreshMode | refreshMode |
| The refresh mode used for Google Tag Manager SDK. | |
| TAGDataLayer * | dataLayer |
| Call push: (TAGDataLayer) method to push events and other data. | |
| NSTimeInterval | dispatchInterval |
| If this value is positive, tracking information will be automatically dispatched every dispatchInterval seconds. | |
Member Function Documentation
| - (TAGContainer *) openContainerById: | (NSString *) | containerId | |
| callback: | (id< TAGContainerCallback >) | callback | |
Returns a container.
Usually the returned container will be empty, but the loading will happen asynchronously, so the returned container may be refreshed before it is returned, after it is returned, or may never be refreshed if, for example, there is no network connection during the lifetime of the container.
Callback will be called as various things happen for the container. At a minimum, openContainerById:callback: will attempt to load a saved version of the container. If there is no saved version, or if the saved version is out of date, attempt will be made to load from the network.
If openContainerById:callback: is called a second time for a given containerId, nil will be returned unless the previous opened container has already been closed.
- Parameters:
-
containerId The ID of the container to open. callback An object whose various methods will be called during the loading process. Note that the methods may be called from different threads. In addition, they may be called before openContainerById:callback: returns.
- Returns:
- The opened container.
| - (TAGContainer *) getContainerById: | (NSString *) | containerId |
Returns the container associated with the given containerId; returns nil if the container is not already open.
| - (BOOL) previewWithUrl: | (NSURL *) | url |
Previews the app with the input url.
The valid url must start with the following:
tagmanager.c.<app_name>://preview/p?id=
where <app_name> is the application name.
- Parameters:
-
url The preview url.
- Returns:
- YES if the url is a valid tagmanager preview url.
| + (TAGManager *) instance |
Gets the singleton instance of the TAGManager class, creating it if necessary.
- Returns:
- The singleton instance of TAGManager.
| - (void) dispatch |
Dispatches any pending network traffic generated by tags (arbitrary pixels, analytics beacons, etc).
| - (void) dispatchWithCompletionHandler: | (TAGDispatchResult) | completionHandler |
Dispatches the next pending network traffic in the queue, calling completionHandler when the request has either been sent (returning kTAGDispatchGood) or an error has resulted (returning kTAGDispatchError).
If there is no network connection or there is no data to send, kTAGDispatchNoData is returned.
Calling this method with a nil completionHandler is the same as calling dispatch.
This method can be used for background data fetching in iOS 7.0 or later.
It would be wise to call this when the application is exiting to initiate the submission of any unsubmitted tracking information.
Property Documentation
The logger to use for Google Tag Manager SDK.
By default, Google Tag Manager logs error/warning messages and ignores info/debug/verbose messages. You can use your own customized logger by setting this property.
- (TAGRefreshMode) refreshMode [read, write, assign] |
The refresh mode used for Google Tag Manager SDK.
Setting this to kTAGRefreshModeDefaultContainer allows the refresh method to use only the default container for development purposes. Default is kTAGRefreshModeStandard.
- (TAGDataLayer*) dataLayer [read, assign] |
Call push: (TAGDataLayer) method to push events and other data.
- (NSTimeInterval) dispatchInterval [read, write, assign] |
If this value is positive, tracking information will be automatically dispatched every dispatchInterval seconds.
Otherwise, tracking information must be sent manually by calling dispatch.
By default, this is set to `120`, which indicates tracking information will be dispatched automatically every 120 seconds.