Add docs for GTM v4

Author: greg-el

docs/data-product-studio/snowtype/working-with-gtm/index.md

@@ -66,6 +66,13 @@ The code that Snowtype will generate is included in a `snowplow.js` file and, as
 Below you can see the steps you need to create the variable using the contents generated by Snowtype:
 ![](./images/gtm-var.gif)
 
+
+:::warning
+
+If the generated code is too large for Google Tag Manager, you can split it into multiple variables and include them in the order they are generated, or place directly into a Custom HTML tag.
+
+:::
+
 ### Naming and calling the Custom JavaScript
 
 After selecting a name for the Custom JavaScript variable, you would need to include it in a [Custom HTML](https://support.google.com/tagmanager/answer/6107167?hl=en#CustomHTML) tag so that it is executed. Depending on your Google Tag Manager setup, there are a couple, or more, places the variable can be used. An example is a type of Custom HTML tag that runs during page initialization:

docs/sources/trackers/google-tag-manager/ecommerce-tag-template/configuration/images/01_ecommerce_api.png

@@ -0,0 +1,98 @@
+---
+title: Ecommerce Tag Configuration
+sidebar_position: 100
+---
+
+```mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+```
+
+## Ecommerce API
+
+Use the native Snowplow Ecommerce API or [transitional GA4/UA ecommerce adapter APIs](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ecommerce/index.md) for existing dataLayer implementations using those formats. To get full value from the [Snowplow Ecommerce plugin](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ecommerce/index.md) we recommend using the native API when possible.
+
+![](images/01_ecommerce_api.png)
+
+## Tracking Parameters
+
+<Tabs groupId="ecommerceAPI" queryString>
+  <TabItem value="sp" label="Snowplow Ecommerce" default>
+
+![](images/02_sp_tracking_parameters.png)
+
+#### Snowplow Ecommerce Function
+
+In this section you can select the [Snowplow Ecommerce function](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ecommerce/index.md) to use.
+
+#### Snowplow Ecommerce Argument
+
+In this textbox you can specify the argument to the ecommerce function. This can be a Variable that evaluates to a corresponding object.
+
+#### Additional Tracking Parameters
+
+**Add Custom Context Entities**
+
+Use this table to attach [custom context entities](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md#custom-context) to the Snowplow event. Each row can be set to a Google Tag Manager variable that returns an array of custom contexts to add to the event hit.
+
+**Set Custom Timestamp**
+
+Set this to a UNIX timestamp in case you want to [override the default timestamp](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md#setting-the-true-timestamp) used by Snowplow.
+
+  </TabItem>
+  <TabItem value="ga4" label="GA4 Ecommerce">
+
+![](images/02_ga4_tracking_parameters.png)
+
+#### GA4 Ecommerce Function
+
+In this section you can select the [Google Analytics 4 Ecommerce function](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ecommerce/index.md) to use.
+
+#### GA4 Ecommerce Arguments
+
+**DataLayer ecommerce**
+
+Here you can specify the dataLayer ecommerce variable to use, i.e. a variable that returns the `ecommerce` object itself.
+
+**Options object**
+
+Here you can specify a variable returning an object holding additional information for the ecommerce event (e.g. including `currency`, `finalCartValue`, `step`, etc).
+
+  </TabItem>
+  <TabItem value="ua" label="Universal Analytics Enhanced Ecommerce">
+
+![](images/02_ua_tracking_parameters.png)
+
+#### Universal Analytics Enhanced Ecommerce Function
+
+In this section you can select the [Universal Analytics Enhanced Ecommerce function](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ecommerce/index.md) to use.
+
+#### Universal Analytics Enhanced Ecommerce Arguments
+
+**DataLayer ecommerce**
+
+Here you can specify the dataLayer ecommerce variable to use.
+
+**Options object**
+
+Here you can specify a variable returning an object holding additional information for the ecommerce event (e.g.including currency, finalCartValue, step etc).
+
+  </TabItem>
+</Tabs>
+
+## Snowplow Tracker and Ecommerce Plugin Settings
+
+![](images/04_tracker_plugin_settings.png)
+
+### Tracker Settings
+
+The Snowplow Ecommerce tag template **requires** a Snowplow Settings Variable to be setup. In this section you can select the Google Tag Manager variable of type [Snowplow Settings](/docs/sources/trackers/google-tag-manager/quick-start/index.md) to use.
+
+### Plugin Settings
+
+In this section you can select how the plugin will be added. The available options are:
+
+- **jsDelivr**: To get the plugin URL from jsDelivr CDN. Choosing this option allows you to specify the plugin version to be used.
+- **unpkg**: To get the plugin URL from unpkg CDN. Choosing this option allows you to specify the plugin version to be used.
+- **Self-hosted**: To get the plugin library from a specified URL. This option requires a [Permission](https://developers.google.com/tag-platform/tag-manager/templates/permissions) change to allow injecting the plugin script from the specified URL.
+- **Do not add**: To not add the plugin (e.g. when using a [Custom Bundle](/docs/sources/trackers/javascript-trackers/web-tracker/plugins/configuring-tracker-plugins/index.md) with the plugin already included)

docs/sources/trackers/google-tag-manager/ecommerce-tag-template/configuration/images/02_ga4_tracking_parameters.png

@@ -0,0 +1,25 @@
+---
+title: Ecommerce Template
+sidebar_position: 600
+---
+
+This template implements the [Snowplow Ecommerce plugin](/docs/sources/trackers/google-tag-manager/ecommerce-tag-template) for the Snowplow JavaScript tracker and is meant to be used alongside [the main Snowplow tag template](/docs/sources/trackers/google-tag-manager/quick-start/index.md#snowplow-tag-template).
+
+## Template Installation
+
+To manually install the tag template:
+
+1. Download [template.tpl](https://github.com/snowplow/snowplow-gtm-tag-template-ecommerce-v3)
+2. Create a new Tag template in the Templates section of your GTM container
+3. Click the More Actions menu and select Import
+4. Import the `template.tpl` file downloaded in Step 1
+5. Click Save
+
+## Tag Setup
+
+With the template installed, you can now add the Snowplow Ecommerce Tag to your GTM Container.
+
+1. From the Tag tab, select `New`, then select the Snowplow Ecommerce Tag as your tag type
+2. Select your desired Trigger for the ecommerce events you want to track
+3. [Configure the Tag]
+4. Click Save

docs/sources/trackers/google-tag-manager/ecommerce-tag-template/configuration/images/02_sp_tracking_parameters.png

@@ -0,0 +1,27 @@
+---
+title: "Google Tag Manager"
+date: "2020-08-10"
+sidebar_position: 3100
+---
+
+
+```mdx-code-block
+import Badges from '@site/src/components/Badges';
+
+<Badges badgeType="Actively Maintained"></Badges>
+```
+
+Using the Snowplow GTM custom templates you can now deploy, implement, and configure the Snowplow JavaScript tracker directly on the website using Google Tag Manager.
+
+The main Tag template that you will need to use when setting up the JavaScript Tracker v4 in GTM is available in the [Tag Manager Template Gallery](https://tagmanager.google.com/gallery/#/owners/snowplow/templates/snowplow-gtm-tag-template-v4). To setup the Snowplow v4 Tag, you will also need the Snowplow v4 Settings Variable template. The templates you will need are:
+
+1. [Snowplow v4 Settings](https://tagmanager.google.com/gallery/#/owners/snowplow/templates/snowplow-gtm-variable-template-v4):
+  A variable template which can be used to easily apply a set of tracker configuration parameters to tags created with the Snowplow v4 tag template.
+2. [Snowplow v4](https://tagmanager.google.com/gallery/#/owners/snowplow/templates/snowplow-gtm-tag-template-v4):
+  Load, configure, and deploy the Snowplow JavaScript tracker library. It supports the full functionality of the JavaScript SDK.
+
+```mdx-code-block
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />
+```

docs/sources/trackers/google-tag-manager/ecommerce-tag-template/configuration/images/02_ua_tracking_parameters.png

@@ -0,0 +1,91 @@
+---
+title: "Plugins"
+sidebar_position: 300
+---
+
+[Plugins](/docs/sources/trackers/google-tag-manager/plugins/index.md) provide an easy way to distribute custom behavior for the tracker.
+Each Plugin can be loaded from external URLs or provided inline within GTM, and can optionally take some custom configuration.
+A Plugin may add new methods to the tracker that can be called via [Custom Commands](#custom-commands).
+
+:::note
+
+Snowplow Plugins are updated alongside the tracker SDK to ensure compatibility. For best results, keep the SDK and plugin versions in sync:
+
+- CDN Users: Use a GTM Variable to manage versions in URLs.
+- Self-Hosting: Update plugin files whenever you update the SDK.
+
+:::
+
+## `Load Plugins` table
+
+Plugins are configured by using the **Load Plugins** table, within the Snowplow tag. Each row takes three values to load a plugin.
+
+:::tip
+
+Plugins are loaded by the tracker SDK directly, not via the Tag Template:
+You do not need to adjust the Template permissions to allow loading plugins from these URLs.
+
+:::
+
+### Plugin URL
+
+The URL to load the Plugin from, e.g. `https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-link-click-tracking@latest/dist/index.umd.min.js`
+
+The tracker will try to load plugins each time they are requested.
+This is usually acceptable as the browser will have cached the first request; if you don't want this behavior we suggest creating an empty **Custom Command** Tag with no commands that loads the plugins; you can make this Tag fire [once per page](https://support.google.com/tagmanager/answer/6279951) and add it as a [Setup Tag](https://support.google.com/tagmanager/answer/6238868) to any other Tags that use its commands.
+
+### Plugin Configuration
+
+The name of the Plugin to load. These values can be found on the respective plugin documentation.
+
+For example, for the `Link Click Tracking` plugin, the values (`'snowplowLinkClickTracking,LinkClickTrackingPlugin'`) can be found in the snippet [here](https://docs.snowplow.io/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/link-click/#enable-link-click-tracking).
+
+### Additional Configuration (optional)
+
+Finally, the optional **Additional Configuration** field allows you to add any configuration the Plugin may require.
+
+There are two ways to format additional configuration:
+
+- A single comma-seperated string value, which will be split into an array of strings and passed as arguments to the Plugin. (e.g. `arg1,arg2,arg3`)
+- A reference to a GTM Variable containing an Array of arguments to pass to the Plugin.
+
+Plugins are loaded in order, and processed before the configured **Tag Type** configuration is executed -- so you can load a plugin in the same Tag that uses its functionality via Custom Commands.
+
+The plugins will remain configured in the tracker and be accessible to later Tags.
+
+:::warning
+
+The Tag Template will try to call `.indexOf(',')` on the **Additional Configuration** value, so values of types other than Array or String may fail and break the Tag.
+String values (before or after splitting) of `true`, `false`, `null`, and numeric values will become their respective typed JSON values.
+It is not possible to pass a single `null`, `undefined`, or empty string value as a parameter to a Plugin, instead no arguments will be passed to the plugin.
+
+:::
+
+## Inline Plugins
+
+[Inline Plugins](/docs/sources/trackers/javascript-trackers/web-tracker/plugins/creating-your-own-plugins/index.md#inline-plugins) are plugins that don't require being fetched from an external file to load.
+
+You can create Inline Plugins in GTM by using Custom JavaScript Variables in the **Plugin URL** field.
+The Variable should return an Object with a method that returns another Object meeting the [Plugin Interface](/docs/sources/trackers/javascript-trackers/web-tracker/plugins/creating-your-own-plugins/index.md#plugin-interface) (any other methods on the outer Object will become tracker methods).
+
+For **Plugin Configuration**, the UI enforces the comma-seperated values syntax required for external Plugins and unconditionally calls `.split(',')` on the string.
+The SDK requires that for inline-plugins only a single string may be used.
+To work around this limitation, create another Custom JavaScript Variable that returns your constructor method name wrapped in an Object with a fake `split()` method:
+
+```javascript
+function() {
+  return {
+    split: function() {
+      return "myInlineConstructorMethodName";
+    }
+  };
+}
+```
+
+:::info
+
+If your configuration includes functions, GTM will wrap those functions in [its sandbox](https://developers.google.com/tag-platform/tag-manager/templates/sandboxed-javascript), even when passed to the SDK for execution.
+
+Complex values like DOM elements will be replaced by `null` when passed to or returned from your function, which may make some plugins not function as intended.
+
+:::

docs/sources/trackers/google-tag-manager/ecommerce-tag-template/configuration/images/04_tracker_plugin_settings.png

@@ -0,0 +1,12 @@
+---
+title: "Previous versions"
+sidebar_position: 1000
+---
+
+In this section you can find out more about the Google Tag Manager custom templates for deploying the previous (v2/v3) versions of the Snowplow JavaScript tracker.
+
+```mdx-code-block
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />
+```

docs/sources/trackers/google-tag-manager/ecommerce-tag-template/configuration/index.md

@@ -0,0 +1,21 @@
+---
+title: v2
+date: "2021-11-18"
+sidebar_position: 1000
+---
+
+Snowplow JavaScript Tracker v2 can now be deployed directly with Google Tag Manager via a Custom Template. This is available in the [Tag Manager Template Gallery](https://tagmanager.google.com/gallery/#/owners/snowplow/templates/snowplow-gtm-custom-template).
+
+There are two templates that you will need to use when setting up the Template for JavaScript Tracker v2.
+
+1. [Snowplow Analytics Settings](https://tagmanager.google.com/gallery/#/owners/snowplow/templates/snowplow-gtm-custom-template-settings)
+2. [Snowplow Analytics](https://tagmanager.google.com/gallery/#/owners/snowplow/templates/snowplow-gtm-custom-template)
+
+Snowplow Analytics Settings Template: A variable template which can be used to easily apply a set of tracker configuration parameters to tags created with the Snowplow Analytics tag template.
+
+Snowplow Analytics Template: Load, configure, and deploy the Snowplow JavaScript tracker library. It supports the full functionality of the JavaScript SDK.
+
+These Custom Templates were created by [Simo Ahava](https://www.simoahava.com/), full documentation can be found on his site:
+
+- [Snowplow Analytics Settings Template Documentation](https://www.simoahava.com/custom-templates/snowplow-analytics-settings/)
+- [Snowplow Analytics Template Documentation](https://www.simoahava.com/custom-templates/snowplow-analytics/)

docs/sources/trackers/google-tag-manager/ecommerce-tag-template/index.md

@@ -0,0 +1,40 @@
+---
+title: "Snowplow v3 Settings Variable"
+sidebar_position: 2000
+---
+
+The **Snowplow v3 Settings** custom variable template is meant to be used with the Snowplow v3 tag template.
+
+With this template, you can compile a **tracker configuration object**, which you can then load into your Snowplow tags to avoid the need to manually enter the same tracker settings across all your tags.
+
+## Install the template
+
+To **install the template**, browse to **Templates** in the Google Tag Manager user interface.
+
+Under **Variable Templates**, click **Search Gallery**, and type `Snowplow v3` into the gallery overlay search bar.
+
+![search Snowplow v3 Settings in GTM gallery](images/search_snowplow_v3_settings.png)
+
+Click the **Snowplow v3 Settings** template name, and then click **Add to Workspace** in the next screen. Review the permissions and click **Add** to finalize the import.
+
+After importing the template, you can follow the normal process of creating a **new variable** in Google Tag Manager, and the **Snowplow v3 Settings** template will be listed among the **Custom** variable types you can choose from.
+
+## Instructions
+
+The fields in the template provide a UI for setting the tracker configuration parameters. You are thus encouraged to follow [this link](/docs/sources/trackers/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md) to understand what each individual field does.
+
+### Tracker Name
+
+It is important to set the **tracker name**. The reason you might have more than one tracker name generated on the site is if you have different configuration objects or tracking endpoints to which you want to send commands.
+
+When the tag runs, it first checks if a tag with this name has already been initialized. If it has, it then proceeds to send the command to this tracker name. If a tracker with this name has _not_ been initialized, a new tracker is initialized with the tracker configuration from this settings variable.
+
+This means that a tracker configuration is applied **only once** to the tracker. Thus if you have more than one tag running on the site, each with the same tracker name but different tracker configurations, only the configuration of the tag that fires _first_ will be applied to the tracker.
+
+### Collector Endpoint Hostname
+
+This needs to be set to the hostname/domain (e.g. `sp.domain.com`) on which you’ve configured your [Snowplow Collector](/docs/pipeline/collector).
+
+## Acknowledgements
+
+Thanks to [Simo Ahava](https://www.simoahava.com/) for building the intial release of this template.