Skip to content

Commit

Permalink
Prepare for MDX v3 migration (#958)
Browse files Browse the repository at this point in the history
* Prepare for MDX3 migration

* Fix TabItem after list

* Fix all “Unsupported Expression” errors

* Fix markdown inside mdx expressions
  • Loading branch information
stanch authored Jul 16, 2024
1 parent 320439b commit e9fb656
Show file tree
Hide file tree
Showing 73 changed files with 493 additions and 506 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -36,14 +36,14 @@ Set the ‘Request Token Encoding’ to JSON and the ‘Request Type’ to POST.
http://collector.domain.com/com.marketo/v1?aid=<company code>
```

To further distinguish the webhooks 3 additional fields are included: “name”, “description” and “step”. In order to populate these fields custom tokens must be created for each webhook. Custom tokens (begins with {{my. followed by the name you created for the token) can be created in either campaign folders or programs. For our custom “step” field please create the custom token as a “number” type.
To further distinguish the webhooks 3 additional fields are included: “name”, “description” and “step”. In order to populate these fields custom tokens must be created for each webhook. Custom tokens (begins with `{{my.` followed by the name you created for the token) can be created in either campaign folders or programs. For our custom “step” field please create the custom token as a “number” type.

In the below example the webhook is called at the 3rd step in Campaign A’s flow.

**_NOTE:_ change the token names for the first 3 fields to align with the event your own webhook is activated on.**

```json
{
{
"name": {{my.Campaign A}},
"description": {{my.Campaign A desc}},
"step": {{my.Campaign A step}},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Choose "HTTP target" from the list of target types to add:

Name the new extension something like "Snowplow Collector - Iglu POST". The "Iglu POST" here represents the fact we will be sending Zendesk events and contexts to [Iglu webhook adapter](/docs/collecting-data/collecting-data-from-third-parties/iglu-webhook/index.md) via `POST` request.

In the **URL** field, enter "https://{{collctor_domain}}/com.snowplowanalytics.iglu/v1?aid=zendesk", replacing `{{collctor_domain}}` with your collector domain.
In the **URL** field, enter `https://{{collector_domain}}/com.snowplowanalytics.iglu/v1?aid=zendesk`, replacing `{{collector_domain}}` with your collector domain.

You can optionally have `?aid={{my_zendesk_namespace}}` added to this URL, where `{{my_zendesk_namespace}}` is a label for the application (here: "zendesk"). This label will be attached to all events fired by the extension, so you can later check where a given event came from (useful if you have more than one Zendesk account).

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,22 +30,22 @@ The best way to deploy this using Google Tag Manager is to replicate the plugin

### 1. Create a new Custom JavaScript variable

Create a new Custom JavaScript variable, and name it {{customTask - Snowplow duplicator}}. Add the following code within:
Create a new Custom JavaScript variable, and name it `{{customTask - Snowplow duplicator}}`. Add the following code within:

```javascript
function() {
// Add your snowplow collector endpoint here
var endpoint = 'https://mycollector.mydomain.com/';

return function(model) {
var vendor = 'com.google.analytics';
var version = 'v1';
var path = ((endpoint.substr(-1) !== '/') ? endpoint + '/' : endpoint) + vendor + '/' + version;

var globalSendTaskName = '_' + model.get('trackingId') + '_sendHitTask';

var originalSendHitTask = window[globalSendTaskName] = window[globalSendTaskName] || model.get('sendHitTask');

model.set('sendHitTask', function(sendModel) {
var payload = sendModel.get('hitPayload');
originalSendHitTask(sendModel);
Expand All @@ -60,7 +60,7 @@ function() {

This stores a reference to the original `sendHitTask` in a globally scoped variable (e.g. `window['_UA-12345-1_sendHitTask']`) to avoid multiple runs of this `customTask` from cascading on each other.

### 2. Add {{customTask - Snowplow duplicator}} to Google Analytics tags
### 2. Add `{{customTask - Snowplow duplicator}}` to Google Analytics tags

This variable must be added to every single Google Analytics tag in the GTM container, whose hits you want to duplicate to Snowplow.

Expand All @@ -71,7 +71,7 @@ Regardless of whether you choose to add this variable directly to the tags' sett
1. Browse to the tags' **More Settings** option, expand it, and then expand **Fields to set**. If you are editing the tag directly (i.e. not using a Google Analytics Settings variable), you will need to check "Enable overriding settings in this tag" first.
2. Add a new field with:
- **Field name**: customTask
- **Value**: {{customTask - Snowplow duplicator}}
- **Value**: `{{customTask - Snowplow duplicator}}`

All tags which have this field set will now send the Google Analytics payload to the Snowplow endpoint.

Expand All @@ -82,7 +82,7 @@ Further reading on the topic:

## Data structure

You can find the specific schema for the properties that will be collected via Google Analytics in the IgluCentral repository:
You can find the specific schema for the properties that will be collected via Google Analytics in the IgluCentral repository:
[Google](https://github.com/snowplow/iglu-central/tree/master/schemas/com.google.analytics)

[Google Measurement Protocol](https://github.com/snowplow/iglu-central/tree/master/schemas/com.google.analytics.measurement-protocol)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,9 @@ function getSnowplowDuid(cookieName) {
var match = document.cookie.match(matcher);
var split = match[1].split('.');
if (match && match[1]) {
return {
'domain_userid': split[0],
'domain_sessionidx': split[2],
return {
'domain_userid': split[0],
'domain_sessionidx': split[2],
'domain_sessionid': split[5]
}
} else {
Expand All @@ -46,18 +46,19 @@ If you set a custom `cookieName` field in the argmap, pass that name into the
It's possible to retrieve cookie properties for use in your code (as well as the [page view UUID](/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/tracking-events/page-views/index.md) and [user ID](/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/tracking-events/#getting-user-id-once-set)) using a tracker callback. This is an advanced usage of the tracker.

```mdx-code-block
import RetrieveValues from "@site/docs/reusable/javascript-tracker-retrieve-values/_index.md"
import RetrieveValuesJs from "@site/docs/reusable/javascript-tracker-retrieve-values/_javascript.md"
import RetrieveValuesBrowser from "@site/docs/reusable/javascript-tracker-retrieve-values/_browser.md"
```

<Tabs groupId="platform" queryString>
<TabItem value="js" label="JavaScript (tag)" default>

<RetrieveValues lang="javascript" />
<RetrieveValuesJs />

</TabItem>
<TabItem value="browser" label="Browser (npm)">

<RetrieveValues lang="browser" />
<RetrieveValuesBrowser />

</TabItem>
</Tabs>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ If no session cookie is already present when an event fires, the tracker treats

Note: A new session can be started at any time by calling the function `newSession`.

When using [anonymous tracking](/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/anonymous-tracking/index.md) with session (`anonymousTracking: { withSessionTracking: true }`; available from v2.15.0+) this key will contain a _salt_ value which is used to stitch page views into a session. The value is never sent to the collector.
When using [anonymous tracking](/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/anonymous-tracking/index.md) with session (`anonymousTracking: { withSessionTracking: true }`; available from v2.15.0+) this key will contain a _salt_ value which is used to stitch page views into a session. The value is never sent to the collector.

### Collector cookie `sp`

Expand All @@ -64,8 +64,8 @@ Local storage will only be used if `stateStorageStrategy` is set to `localSto

| Storage key | Description |
|--------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| snowplowOutQueue_{namespace}_post2 | Used to store a cache of unsent events. This is used to reduce the chance of events to be lost due to page navigation and events not being set to the collector before the navigation event occurs. Where GET requests are used, this key will end in `_get` rather than `_post2`. |
| snowplowOutQueue_{namespace}_post2.expires | Used to match the concept of cookie expiry within local storage. This ensures a consistent behavior between cookie and local storage. Where GET requests are used, this key will end in `_get` rather than `_post2`. |
| `snowplowOutQueue_{namespace}_post2` | Used to store a cache of unsent events. This is used to reduce the chance of events to be lost due to page navigation and events not being set to the collector before the navigation event occurs. Where GET requests are used, this key will end in `_get` rather than `_post2`. |
| `snowplowOutQueue_{namespace}_post2.expires` | Used to match the concept of cookie expiry within local storage. This ensures a consistent behavior between cookie and local storage. Where GET requests are used, this key will end in `_get` rather than `_post2`. |

## Mapping values to tracker protocol

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@ sidebar_position: 3000
```mdx-code-block
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import ReleaseBadge from '@site/docs/reusable/javascript-tracker-release-badge-v3/_index.md'
import ReleaseBadge from '@site/docs/reusable/javascript-tracker-release-badge-v3/_index.md';
<ReleaseBadge/>
```

Expand Down Expand Up @@ -44,7 +45,7 @@ The responsibilities of this service are:

_The new unique identifier cookie for sake of simplicity in this document will have the name `spIdService`._

### ID service business logic
### ID service business logic

The ID service code should include the following logic:

Expand All @@ -53,7 +54,7 @@ The ID service code should include the following logic:
- If `spIdService` and `sp` are both missing, then it generates a new ID in the `spIdService` and `sp` cookies with the same unique identifier generation algorithm with the Snowplow pipeline, currently UUID v4.
- The HTTP response should have a 200 OK status code but any additional payload is not necessary.

### Code examples
### Code examples

Below we showcase a couple of code samples for ID service API endpoints:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ sidebar_position: 6500
---

```mdx-code-block
import ReleaseBadge from '@site/docs/reusable/javascript-tracker-release-badge-v3/_index.md'
import ReleaseBadge from '@site/docs/reusable/javascript-tracker-release-badge-v3/_index.md';
<ReleaseBadge/>
```

Expand All @@ -26,24 +27,24 @@ The plugin is available since version 3.8 of the tracker.
import { newTracker } from '@snowplow/browser-tracker';
import { EnhancedConsentPlugin } from '@snowplow/browser-plugin-enhanced-consent';

newTracker('sp1', '{{collector_url}}', {
appId: 'my-app-id',
newTracker('sp1', '{{collector_url}}', {
appId: 'my-app-id',
plugins: [ EnhancedConsentPlugin() ],
});
```

## Functions

API | Used for:
-- | --
-- | --
`trackConsentAllow` | Track an acceptance of user consent.
`trackConsentSelected` | Track a specific selection of consented scopes.
`trackConsentPending` | Track the unconfirmed selection about user consent.
`trackConsentImplicit` | Track the implicit consent on user consent preferences.
`trackConsentDeny` | Track a denial of user consent.
`trackConsentExpired` | Track the expiration of a consent selection.
`trackConsentWithdrawn` | Track the withdrawal of user consent.
`trackCmpVisible` | Track the render time of a CMP banner.
`trackCmpVisible` | Track the render time of a CMP banner.

## Usage

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ If this plugin is enabled, the tracker will attempt to create a context from the
## Installation

- `npm install @snowplow/browser-plugin-geolocation`
- ``yarn add @snowplow/browser-plugin-`geolocation` ``
- ``pnpm add @snowplow/browser-plugin-`geolocation` ``
- `yarn add @snowplow/browser-plugin-geolocation`
- `pnpm add @snowplow/browser-plugin-geolocation`

## Initialization

Expand All @@ -34,11 +34,16 @@ enableGeolocationContext();

### Functions

<table class="has-fixed-layout"><tbody><tr><td><code>enableGeolocationContext</code></td><td>
<table class="has-fixed-layout"><tbody>
<tr>
<td><code>enableGeolocationContext</code></td>
<td>

[Documentation](/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/tracker-setup/initialization-options/index.md)

</td></tr></tbody></table>
</td>
</tr>
</tbody></table>

### Context

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ sidebar_position: 16000
---

```mdx-code-block
import ReleaseBadge from '@site/docs/reusable/javascript-tracker-release-badge-v3/_index.md'
import ReleaseBadge from '@site/docs/reusable/javascript-tracker-release-badge-v3/_index.md';
<ReleaseBadge/>
```

Expand All @@ -26,17 +27,17 @@ The plugin is available since version 3.8 of the tracker.
import { newTracker } from '@snowplow/browser-tracker';
import { SnowplowEcommercePlugin } from '@snowplow/browser-plugin-snowplow-ecommerce';

newTracker('sp1', '{{collector_url}}', {
appId: 'my-app-id',
newTracker('sp1', '{{collector_url}}', {
appId: 'my-app-id',
plugins: [ SnowplowEcommercePlugin() ],
});
```

## Functions

API | Used for:
-- | --
`trackProductView` | Tracking a visit to a product page. Known also as product detail view.
-- | --
`trackProductView` | Tracking a visit to a product page. Known also as product detail view.
`trackAddToCart` | Track an addition to cart.
`trackRemoveFromCart` | Track a removal from cart.
`trackProductListView` | Track an impression of a product list. The list could be a search results page, recommended products, upsells etc.
Expand Down Expand Up @@ -198,7 +199,7 @@ trackProductListClick({
import { trackPromotionView } from '@snowplow/browser-plugin-snowplow-ecommerce';

/* Carousel slide 1 viewed */
trackPromotionView({
trackPromotionView({
id: 'IP1234',
name: 'promo_winter',
type: 'carousel',
Expand All @@ -207,7 +208,7 @@ trackPromotionView({
});

/* On carousel slide 2 view */
trackPromotionView({
trackPromotionView({
id: 'IP1234',
name: 'promo_winter',
type: 'carousel',
Expand All @@ -221,7 +222,7 @@ trackPromotionView({
```js
import { trackPromotionClick } from "@snowplow/browser-plugin-snowplow-ecommerce";

trackPromotionClick({
trackPromotionClick({
id: 'IP1234',
name: 'promo_winter',
type: 'carousel',
Expand Down Expand Up @@ -521,7 +522,7 @@ Available from version 3.10.

If you already use Google Analytics 4 ecommerce or Universal Analytics Enhanced Ecommerce to collect information about the shopping behavior of your users, we have prepared a way to quickly implement Snowplow Ecommerce without making many changes on your current setup.

The _transitional_ API that we provide, depends on the standardized [dataLayer](https://developers.google.com/tag-platform/tag-manager/web/datalayer) structure for both Google Analytics ecommerce implementations. This would make it easier for the transition to happen either through Google Tag Manager, which has more control over the dataLayer, or custom code that uses the standard ecommerce structures.
The _transitional_ API that we provide, depends on the standardized [dataLayer](https://developers.google.com/tag-platform/tag-manager/web/datalayer) structure for both Google Analytics ecommerce implementations. This would make it easier for the transition to happen either through Google Tag Manager, which has more control over the dataLayer, or custom code that uses the standard ecommerce structures.

:::info
To learn more about how to use this transitional API, you should go ahead and visit our [Ecommerce Web Accelerator](https://docs.snowplow.io/accelerators/ecommerce/tracking/ua_ga4_migration/) dedicated page which describes the usage of these methods and more.
Expand Down Expand Up @@ -641,7 +642,7 @@ trackEnhancedEcommercePurchase( {{dataLayer.ecommerce reference}}, {
});
```

- Where `paymentMethod` is the payment method selected in this transaction. This attributes corresponds to the `payment_method` of the [transaction schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.ecommerce/transaction/jsonschema/1-0-0#L30). Defaults to `unknown`.
- Where `paymentMethod` is the payment method selected in this transaction. This attributes corresponds to the `payment_method` of the [transaction schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.ecommerce/transaction/jsonschema/1-0-0#L30). Defaults to `unknown`.

### Google Analytics 4 Ecommerce

Expand Down Expand Up @@ -785,4 +786,4 @@ trackGA4Transaction({
});
```

- Where `paymentMethod` is the payment method selected in this transaction. This attributes corresponds to the `payment_method` of the [transaction schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.ecommerce/transaction/jsonschema/1-0-0#L30). Defaults to `unknown`.
- Where `paymentMethod` is the payment method selected in this transaction. This attributes corresponds to the `payment_method` of the [transaction schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.ecommerce/transaction/jsonschema/1-0-0#L30). Defaults to `unknown`.
Loading

0 comments on commit e9fb656

Please sign in to comment.