diff --git a/.github/styles/Snowplow/Acronyms.yml b/.github/styles/Snowplow/Acronyms.yml index d386c1dae4..b2111bc7d7 100644 --- a/.github/styles/Snowplow/Acronyms.yml +++ b/.github/styles/Snowplow/Acronyms.yml @@ -10,6 +10,7 @@ second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' exceptions: - API - ASP + - CDN - CLI - CPU - CSS diff --git a/.github/styles/Snowplow/Headings.yml b/.github/styles/Snowplow/Headings.yml index 6fbbe9abaa..de4fc93f7e 100644 --- a/.github/styles/Snowplow/Headings.yml +++ b/.github/styles/Snowplow/Headings.yml @@ -9,6 +9,7 @@ exceptions: - CLI - Cosmos - Docker + - DOM - Emmet - gRPC - I diff --git a/.github/styles/config/vocabularies/snowplow/accept.txt b/.github/styles/config/vocabularies/snowplow/accept.txt index 5f6e07eb90..00593edd78 100644 --- a/.github/styles/config/vocabularies/snowplow/accept.txt +++ b/.github/styles/config/vocabularies/snowplow/accept.txt @@ -139,3 +139,5 @@ READMEs [uU]tils [vV]iewport [wW]alkthrough + +agentic diff --git a/.gitignore b/.gitignore index 408f2a80d7..6e7b4d92b9 100644 --- a/.gitignore +++ b/.gitignore @@ -28,3 +28,6 @@ yarn-error.log* # Python __pycache__ manifests + +# Local Netlify folder +.netlify diff --git a/README.md b/README.md index b38bb8c097..4ac50894c5 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ Vale only checks normal prose. Text that's marked as code—code blocks or in-li To install the extension, find "[Vale VSCode](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode)" in the Extensions Marketplace within VS Code, then click **Install**. -The Vale extension will automatically check files when they're opened or saved. It underlines the flagged sections in different colours, based on the severity of the alert - red for errors, orange for warnings, and blue for suggestions. Mouse-over the underlined section to see the alert message, or check the VS Code **Problems** tab. +The Vale extension will automatically check files when they're opened or saved. It underlines the flagged sections in different colors, based on the severity of the alert - red for errors, orange for warnings, and blue for suggestions. Mouse-over the underlined section to see the alert message, or check the VS Code **Problems** tab. ### Vale command-line interface diff --git a/docs/api-reference/failed-events/index.md b/docs/api-reference/failed-events/index.md index eb98ec9956..35078f6619 100644 --- a/docs/api-reference/failed-events/index.md +++ b/docs/api-reference/failed-events/index.md @@ -116,7 +116,7 @@ Adapter failure schema can be found [here](https://github.com/snowplow/iglu-cent ## Tracker protocol violation -This failure type is produced by the [Enrich](/docs/pipeline/enrichments/index.md) application, when an HTTP request does not conform to our [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +This failure type is produced by the [Enrich](/docs/pipeline/enrichments/index.md) application, when an HTTP request does not conform to our [Snowplow Tracker Protocol](/docs/events/index.md).
diff --git a/docs/api-reference/loaders-storage-targets/bigquery-loader/_deploy-overview.md b/docs/api-reference/loaders-storage-targets/bigquery-loader/_deploy-overview.md index 90ecf442b6..addcabdf57 100644 --- a/docs/api-reference/loaders-storage-targets/bigquery-loader/_deploy-overview.md +++ b/docs/api-reference/loaders-storage-targets/bigquery-loader/_deploy-overview.md @@ -19,4 +19,4 @@ To run the loader, mount your config file into the docker image, and then provid --iglu-config /myconfig/iglu.hocon `} -Where `loader.hocon` is loader's [configuration file](/docs/api-reference/loaders-storage-targets/bigquery-loader/#configuring-the-loader) and `iglu.hocon` is [iglu resolver](/docs/api-reference/iglu/iglu-resolver/index.md) configuration. +Where `loader.hocon` is loader's [configuration file](/docs/api-reference/loaders-storage-targets/bigquery-loader/index.md#configuring-the-loader) and `iglu.hocon` is [iglu resolver](/docs/api-reference/iglu/iglu-resolver/index.md) configuration. diff --git a/docs/api-reference/loaders-storage-targets/lake-loader/configuration-reference/_hudi_config.md b/docs/api-reference/loaders-storage-targets/lake-loader/configuration-reference/_hudi_config.md deleted file mode 100644 index 125de69354..0000000000 --- a/docs/api-reference/loaders-storage-targets/lake-loader/configuration-reference/_hudi_config.md +++ /dev/null @@ -1,19 +0,0 @@ - - output.good.location - - Required, e.g. gs://mybucket/events. URI of the bucket location to which to write Snowplow enriched events in Hudi format. The URI should start with the following prefix: - - - - - output.good.hudiWriteOptions.* - Optional. A map of key/value strings corresponding to Hudi's configuration options for writing into a table. The default options configure load_tstamp as the table's partition field. - - - output.good.hudiTableProperties.* - Optional. A map of key/value strings corresponding to Hudi's configuration options for creating a table. The default options configure load_tstamp as the table's partition field. - diff --git a/docs/api-reference/loaders-storage-targets/lake-loader/configuration-reference/index.md b/docs/api-reference/loaders-storage-targets/lake-loader/configuration-reference/index.md index 9268283554..55097e4bab 100644 --- a/docs/api-reference/loaders-storage-targets/lake-loader/configuration-reference/index.md +++ b/docs/api-reference/loaders-storage-targets/lake-loader/configuration-reference/index.md @@ -9,7 +9,6 @@ import {versions} from '@site/src/componentVersions'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import DeltaConfig from '@site/docs/api-reference/loaders-storage-targets/lake-loader/configuration-reference/_delta_config.md'; -import HudiConfig from '@site/docs/api-reference/loaders-storage-targets/lake-loader/configuration-reference/_hudi_config.md'; import IcebergBigLakeConfig from '@site/docs/api-reference/loaders-storage-targets/lake-loader/configuration-reference/_iceberg_biglake_config.md'; import IcebergGlueConfig from '@site/docs/api-reference/loaders-storage-targets/lake-loader/configuration-reference/_iceberg_glue_config.md'; import PubsubConfig from '@site/docs/api-reference/loaders-storage-targets/lake-loader/configuration-reference/_pubsub_config.md'; @@ -52,23 +51,6 @@ import Admonition from '@theme/Admonition'; - - - To use the Lake Loader with Hudi support, pull the appropriate alternative image from Docker Hub, e.g. snowplow/lake-loader-aws:{`${versions.lakeLoader}`}-hudi. - - - - - - - - - - - -
ParameterDescription
- - ### Streams configuration diff --git a/docs/api-reference/loaders-storage-targets/lake-loader/index.md b/docs/api-reference/loaders-storage-targets/lake-loader/index.md index e87c625303..cfd63fe125 100644 --- a/docs/api-reference/loaders-storage-targets/lake-loader/index.md +++ b/docs/api-reference/loaders-storage-targets/lake-loader/index.md @@ -17,7 +17,7 @@ The Lake Loader is an application that loads Snowplow events to a cloud storage :::info Open Table Formats -The Lake Loader supports the three major Open Table Formats: [Delta](https://delta.io/), [Iceberg](https://iceberg.apache.org/) and [Hudi](https://hudi.apache.org/). +The Lake Loader supports the two major Open Table Formats: [Delta](https://delta.io/) and [Iceberg](https://iceberg.apache.org/). For Iceberg tables, the loader supports [AWS Glue](https://docs.aws.amazon.com/glue/) as catalog. diff --git a/docs/api-reference/loaders-storage-targets/snowplow-postgres-loader/postgres-loader-configuration-reference/index.md b/docs/api-reference/loaders-storage-targets/snowplow-postgres-loader/postgres-loader-configuration-reference/index.md index 1be2e56e33..b034e317e0 100644 --- a/docs/api-reference/loaders-storage-targets/snowplow-postgres-loader/postgres-loader-configuration-reference/index.md +++ b/docs/api-reference/loaders-storage-targets/snowplow-postgres-loader/postgres-loader-configuration-reference/index.md @@ -6,10 +6,10 @@ sidebar_position: 0 This is a complete list of the options that can be configured in the postgres loader's HOCON config file. The [example configs in github](https://github.com/snowplow-incubator/snowplow-postgres-loader/tree/master/config) show how to prepare an input file. -
input.typeRequired. Can be "Kinesis", "PubSub" or "Local". Configures where input events will be read from.
input.streamNameRequired when input.type is Kinesis. Name of the Kinesis stream to read from.
input.regionRequired when input.type is Kinesis. AWS region in which the Kinesis stream resides.
input.initialPositionOptional. Used when input.type is Kinesis. Use "TRIM_HORIZON" (the default) to start streaming at the last untrimmed record in the shard, which is the oldest data record in the shard. Or use "LATEST" to start streaming just after the most recent record in the shard.
input.retrievalMode.typeOptional. When input.type is Kinesis, this sets the polling mode for retrieving records. Can be "FanOut" (the default) or "Polling".
input.retrievalMode.maxRecordsOptional. Used when input.retrievalMode.type is "Polling". Configures how many records are fetched in each poll of the kinesis stream. Default 10000.
input.projectIdRequired when input.type is PubSub. The name of your GCP project.
input.subscriptionIdRequired when input.type is PubSub. Id of the PubSub subscription to read events from
input.pathRequired when input.type is Local. Path for event source. It can be directory or file. If it is directory, all the files under given directory will be read recursively. Also, given path can be both absolute path or relative path w.r.t. executable.
output.good.hostRequired. Hostname of the postgres database.
output.good.portOptional. Port number of the postgres database. Default 5432.
output.good.databaseRequired. Name of the postgres database.
output.good.usernameRequired. Postgres role name to use when connecting to the database
output.good.passwordRequired. Password for the postgres user.
output.good.schemaRequired. The Postgres schema in which to create tables and write events.
output.good.sslModeOptional. Configures how the client and server agree on ssl protection. Default "REQUIRE"
output.bad.typeOptional. Can be "Kinesis", "PubSub", "Local" or "Noop". Configures where failed events will be sent. Default is "Noop" which means failed events will be discarded
output.bad.streamNameRequired when bad.type is Kinesis. Name of the Kinesis stream to write to.
output.bad.regionRequired when bad.type is Kinesis. AWS region in which the Kinesis stream resides.
output.bad.projectIdRequired when bad.type is PubSub. The name of your GCP project.
output.bad.topicIdRequired when bad.type is PubSub. Id of the PubSub topic to write failed events to
output.bad.pathRequired when bad.type is Local. Path of the file to write failed events
purposeOptional. Set this to "ENRICHED_EVENTS" (the default) when reading the stream of enriched events in tsv format. Set this to "JSON" when reading a stream of self-describing json, e.g. snowplow [bad rows](https://github.com/snowplow/iglu-central/tree/master/schemas/com.snowplowanalytics.snowplow.badrows).
monitoring.metrics.cloudWatchOptional boolean, with default true. For kinesis input, this is used to disable sending metrics to cloudwatch.
+
input.typeRequired. Can be "Kinesis", "PubSub" or "Local". Configures where input events will be read from.
input.streamNameRequired when input.type is Kinesis. Name of the Kinesis stream to read from.
input.regionRequired when input.type is Kinesis. AWS region in which the Kinesis stream resides.
input.initialPositionOptional. Used when input.type is Kinesis. Use "TRIM_HORIZON" (the default) to start streaming at the last untrimmed record in the shard, which is the oldest data record in the shard. Or use "LATEST" to start streaming just after the most recent record in the shard.
input.retrievalMode.typeOptional. When input.type is Kinesis, this sets the polling mode for retrieving records. Can be "FanOut" (the default) or "Polling".
input.retrievalMode.maxRecordsOptional. Used when input.retrievalMode.type is "Polling". Configures how many records are fetched in each poll of the kinesis stream. Default 10000.
input.projectIdRequired when input.type is PubSub. The name of your GCP project.
input.subscriptionIdRequired when input.type is PubSub. Id of the PubSub subscription to read events from
input.pathRequired when input.type is Local. Path for event source. It can be directory or file. If it is directory, all the files under given directory will be read recursively. Also, given path can be both absolute path or relative path w.r.t. executable.
output.good.hostRequired. Hostname of the postgres database.
output.good.portOptional. Port number of the postgres database. Default 5432.
output.good.databaseRequired. Name of the postgres database.
output.good.usernameRequired. Postgres role name to use when connecting to the database
output.good.passwordRequired. Password for the postgres user.
output.good.schemaRequired. The Postgres schema in which to create tables and write events.
output.good.sslModeOptional. Configures how the client and server agree on ssl protection. Default "REQUIRE"
output.bad.typeOptional. Can be "Kinesis", "PubSub", "Local" or "Noop". Configures where failed events will be sent. Default is "Noop" which means failed events will be discarded
output.bad.streamNameRequired when bad.type is Kinesis. Name of the Kinesis stream to write to.
output.bad.regionRequired when bad.type is Kinesis. AWS region in which the Kinesis stream resides.
output.bad.projectIdRequired when bad.type is PubSub. The name of your GCP project.
output.bad.topicIdRequired when bad.type is PubSub. Id of the PubSub topic to write failed events to
output.bad.pathRequired when bad.type is Local. Path of the file to write failed events
purposeOptional. Set this to "ENRICHED_EVENTS" (the default) when reading the stream of enriched events in tsv format. Set this to "JSON" when reading a stream of self-describing json, e.g. snowplow [bad rows](https://github.com/snowplow/iglu-central/tree/master/schemas/com.snowplowanalytics.snowplow.badrows).
monitoring.metrics.cloudWatchOptional boolean, with default true. For kinesis input, this is used to disable sending metrics to cloudwatch.
#### Advanced options We believe these advanced options are set to sensible defaults, and hopefully you won't need to ever change them. -
backoffPolicy.minBackoffIf producer (PubSub or Kinesis) fails to send item, it will retry to send it again. This field configures backoff time for first retry. Every retry will double the backoff time of previous one.
backoffPolicy.maxBackoffMaximum backoff time for retry. After this value is reached, backoff time will no more increase.
input.checkpointSettings.maxBatchSizeUsed when input.type is Kinesis. Determines the max number of records to aggregate before checkpointing the records. Default is 1000.
input.checkpointSettings.maxBatchWaitUsed when input.type is Kinesis. Determines the max amount of time to wait before checkpointing the records. Default is 10 seconds.
input.checkpointSettings.maxConcurrentUsed when input.type is PubSub. The max number of concurrent evaluation for checkpointer.
output.good.maxConnectionsMaximum number of connections database pool is allowed to reach. Default 10
output.good.threadPoolSizeSize of the thread pool for blocking database operations. Default is value of "maxConnections"
output.bad.delayThresholdSet the delay threshold to use for batching. After this amount of time has elapsed (counting from the first element added), the elements will be wrapped up in a batch and sent. Default 200 milliseconds
output.bad.maxBatchSizeA batch of messages will be emitted when the number of events in batch reaches the given size. Default 500
output.bad.maxBatchBytesA batch of messages will be emitted when the size of the batch reaches the given size. Default 5 MB
+
backoffPolicy.minBackoffIf producer (PubSub or Kinesis) fails to send item, it will retry to send it again. This field configures backoff time for first retry. Every retry will double the backoff time of previous one.
backoffPolicy.maxBackoffMaximum backoff time for retry. After this value is reached, backoff time will no more increase.
input.checkpointSettings.maxBatchSizeUsed when input.type is Kinesis. Determines the max number of records to aggregate before checkpointing the records. Default is 1000.
input.checkpointSettings.maxBatchWaitUsed when input.type is Kinesis. Determines the max amount of time to wait before checkpointing the records. Default is 10 seconds.
input.checkpointSettings.maxConcurrentUsed when input.type is PubSub. The max number of concurrent evaluation for checkpointer.
output.good.maxConnectionsMaximum number of connections database pool is allowed to reach. Default 10
output.good.threadPoolSizeSize of the thread pool for blocking database operations. Default is value of "maxConnections"
output.bad.delayThresholdSet the delay threshold to use for batching. After this amount of time has elapsed (counting from the first element added), the elements will be wrapped up in a batch and sent. Default 200 milliseconds
output.bad.maxBatchSizeA batch of messages will be emitted when the number of events in batch reaches the given size. Default 500
output.bad.maxBatchBytesA batch of messages will be emitted when the size of the batch reaches the given size. Default 5 MB
diff --git a/docs/data-product-studio/data-products/data-product-templates/index.md b/docs/data-product-studio/data-products/data-product-templates/index.md index 4c397d4483..a48799f537 100644 --- a/docs/data-product-studio/data-products/data-product-templates/index.md +++ b/docs/data-product-studio/data-products/data-product-templates/index.md @@ -39,17 +39,17 @@ Note: The event volume counts are calculated differently for this Data Product. Included event specifications: -* [Screen view](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-and-screen-view-events/index.md#screen-view-events) -* [Screen end](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md#screen-end-event) -* [Application install](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#install-event) -* [Application background](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#background-event) -* [Application foreground](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#foreground-event) +* [Screen view](/docs/events/ootb-data/page-and-screen-view-events/index.md#screen-view-events) +* [Screen end](/docs/events/ootb-data/page-activity-tracking/index.md#screen-end-event) +* [Application install](/docs/events/ootb-data/mobile-lifecycle-events/index.md#install-event) +* [Application background](/docs/events/ootb-data/mobile-lifecycle-events/index.md#background-event) +* [Application foreground](/docs/events/ootb-data/mobile-lifecycle-events/index.md#foreground-event) ### E-commerce (Web and Mobile) This Data Product template contains all the basic e-commerce interactions that help you analyze customer behavior, identify potential growth opportunities, and improve your sales performance. -Tracked using the [out-of-the-box e-commerce events](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/ecommerce-events/index.md) for web, Android, and iOS. On web, this requires the [Snowplow Ecommerce plugin](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ecommerce/index.md). +Tracked using the [out-of-the-box e-commerce events](/docs/events/ootb-data/ecommerce-events/index.md) for web, Android, and iOS. On web, this requires the [Snowplow Ecommerce plugin](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ecommerce/index.md). Included event specifications: diff --git a/docs/data-product-studio/data-products/ui/images/create-data-product-modal.png b/docs/data-product-studio/data-products/ui/images/create-data-product-modal.png index a10b2be10e..1c391ebb3c 100644 Binary files a/docs/data-product-studio/data-products/ui/images/create-data-product-modal.png and b/docs/data-product-studio/data-products/ui/images/create-data-product-modal.png differ diff --git a/docs/data-product-studio/data-products/ui/images/create-data-product-v2.png b/docs/data-product-studio/data-products/ui/images/create-data-product-v2.png index 9cf6bb8f0a..9763bd244e 100644 Binary files a/docs/data-product-studio/data-products/ui/images/create-data-product-v2.png and b/docs/data-product-studio/data-products/ui/images/create-data-product-v2.png differ diff --git a/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/alerts/images/image-1.png b/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/alerts/images/image-1.png index 5a9f225b77..3b44b75d06 100644 Binary files a/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/alerts/images/image-1.png and b/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/alerts/images/image-1.png differ diff --git a/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/alerts/images/image.png b/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/alerts/images/image.png index 3078fb883a..f8174942bb 100644 Binary files a/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/alerts/images/image.png and b/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/alerts/images/image.png differ diff --git a/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/alerts/index.md b/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/alerts/index.md index 870f43c51d..f661a0c35a 100644 --- a/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/alerts/index.md +++ b/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/alerts/index.md @@ -20,8 +20,7 @@ To receive alerts you must have the Failed Events monitoring feature switched on - Login to Snowplow BDP console - Locate the pipeline you wish to set up alerts for in the left-hand navigation -- Find and select `Pipeline configuration` -- Scroll down to `Pipeline alerts` or use the page navigation to jump to it +- Click on the `Configuration` tab, then the `Pipeline alerts` section ![](images/image.png) diff --git a/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/index.md b/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/index.md index 5bc51bc2ec..eb776cad62 100644 --- a/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/index.md +++ b/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/index.md @@ -35,7 +35,7 @@ We've filtered on these two types of errors to reduce noise like bot traffic tha At the top there is a data quality score that compares the volume of failed events to the volume that were successfully loaded into a data warehouse. -The bar chart shows how the total number of failed events varies over time, colour-coding validation and enrichment errors. The time window is 7 days be default but can be extended to 14 or 30 days. +The bar chart shows how the total number of failed events varies over time, color-coding validation and enrichment errors. The time window is 7 days be default but can be extended to 14 or 30 days. In the table, failed events are aggregated by the unique type of failure (validation, enrichment) and the offending schema. @@ -49,7 +49,7 @@ The detailed view shows the error message as well as other useful metadata (when The data quality dashboard allows you to see failed events directly from your warehouse. Your browser connects directly to an API running within your infrastructure, such that no failed event information flows through Snowplow. The discussion of architecture is important as it highlights the trade-offs between the two ways of monitoring failed events. The aforementioned API is a simple proxy that connects to your warehouse and serves the failed events to your browser. The connection is fully secure, using an encrypted channel (HTTPS) and authenticating/authorizing via the same mechanism used by Console. -In order for you to be able to deploy and use the data quality dashboard, you need to sink failed events to the warehouse via a [Failed Events Loader](/docs/data-product-studio/data-quality/failed-events/exploring-failed-events/warehouse-lake/#setup). The data quality dashboard only supports Snowflake. +In order for you to be able to deploy and use the data quality dashboard, you need to sink failed events to the warehouse via a [Failed Events Loader](/docs/data-product-studio/data-quality/failed-events/exploring-failed-events/index.md#configure). The data quality dashboard currently supports Snowflake and Bigquery connections. ![](images/dqd-architecture.png) @@ -67,7 +67,7 @@ Clicking on a particular error type will take you to a detailed view: ![](images/dqd-details.png) -The detailed view also shows a description of the root cause and the application version ([web](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/app-information/#application-context-entity-on-web-apps), [mobile](/docs/sources/trackers/mobile-trackers/tracking-events/platform-and-application-context/)). It provides a sample of the failed events in their entirety, as found in your warehouse. +The detailed view also shows a description of the root cause and the application version ([web](/docs/events/ootb-data/app-information/index.md#application-context-entity-on-web-apps), [mobile](/docs/sources/trackers/mobile-trackers/tracking-events/platform-and-application-context/index.md)). It provides a sample of the failed events in their entirety, as found in your warehouse. Some columns are too wide to fit in the table: click on them to see the full pretty-printed, syntax-highlighted content. The most useful column to explore is probably `CONTEXTS_COM_SNOWPLOWANALYTICS_SNOWPLOW_FAILURE_1`, which contains the actual error information encoded as a JSON object: diff --git a/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-filters-to-your-recovery/images/Screen-Shot-2021-10-13-at-16.14.27.jpg b/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-filters-to-your-recovery/images/Screen-Shot-2021-10-13-at-16.14.27.jpg index a80c716b41..dbd3b4d5f2 100644 Binary files a/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-filters-to-your-recovery/images/Screen-Shot-2021-10-13-at-16.14.27.jpg and b/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-filters-to-your-recovery/images/Screen-Shot-2021-10-13-at-16.14.27.jpg differ diff --git a/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-filters-to-your-recovery/images/Screen-Shot-2021-10-13-at-16.16.42.jpg b/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-filters-to-your-recovery/images/Screen-Shot-2021-10-13-at-16.16.42.jpg index 1c7ef2dca1..e7107019e9 100644 Binary files a/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-filters-to-your-recovery/images/Screen-Shot-2021-10-13-at-16.16.42.jpg and b/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-filters-to-your-recovery/images/Screen-Shot-2021-10-13-at-16.16.42.jpg differ diff --git a/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-filters-to-your-recovery/images/batch-test-filters.jpg b/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-filters-to-your-recovery/images/batch-test-filters.jpg index 8704062dd1..431d92be3b 100644 Binary files a/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-filters-to-your-recovery/images/batch-test-filters.jpg and b/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-filters-to-your-recovery/images/batch-test-filters.jpg differ diff --git a/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-add-1.jpg b/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-add-1.jpg index 3636923a39..70f52c4a3b 100644 Binary files a/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-add-1.jpg and b/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-add-1.jpg differ diff --git a/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-add-2.jpg b/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-add-2.jpg index 501f31d825..d407379ae8 100644 Binary files a/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-add-2.jpg and b/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-add-2.jpg differ diff --git a/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-add-3.jpg b/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-add-3.jpg index fb69ce3320..1ca5cc01bc 100644 Binary files a/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-add-3.jpg and b/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-add-3.jpg differ diff --git a/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-recomms.jpg b/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-recomms.jpg index 3c64552a69..915054bd49 100644 Binary files a/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-recomms.jpg and b/docs/data-product-studio/data-quality/failed-events/recovering-failed-events/builder/adding-recovery-steps/images/failed-evs-steps-recomms.jpg differ diff --git a/docs/data-product-studio/data-quality/snowplow-micro/automated-testing/index.md b/docs/data-product-studio/data-quality/snowplow-micro/automated-testing/index.md index f2e3a6213c..afb12a14d0 100644 --- a/docs/data-product-studio/data-quality/snowplow-micro/automated-testing/index.md +++ b/docs/data-product-studio/data-quality/snowplow-micro/automated-testing/index.md @@ -486,7 +486,7 @@ Generally, a test involves 3 phases: While Cypress considers as state the application's state, it is still a fact that an app is rarely an isolated system without side effects. -This is especially true when a tracking strategy is implemented, which means that any action can fire [events](/docs/sources/trackers/snowplow-tracker-protocol/index.md) through the [trackers](/docs/sources/trackers/index.md). There is an increasing number of reports highlighting the importance of upstream data quality and Data Ops, which means that testing your Data Collection and trackers' implementation besides your product's features is of highest priority. Tracking is as important as your shipping, and that is why it is highly recommended that you include its testing in your E2E tests. +This is especially true when a tracking strategy is implemented, which means that any action can fire [events](/docs/events/index.md) through the [trackers](/docs/sources/trackers/index.md). There is an increasing number of reports highlighting the importance of upstream data quality and Data Ops, which means that testing your Data Collection and trackers' implementation besides your product's features is of highest priority. Tracking is as important as your shipping, and that is why it is highly recommended that you include its testing in your E2E tests. Cypress, even though it considers as [best practice](https://docs.cypress.io/guides/references/best-practices.html#Visiting-external-sites) to avoid requiring or testing 3rd party services, it still offers the ability to "talk" to 3rd party API's via [cy.request()](https://docs.cypress.io/api/commands/request.html), that: diff --git a/docs/data-product-studio/data-structures/index.md b/docs/data-product-studio/data-structures/index.md index 15f8199852..b43272c582 100644 --- a/docs/data-product-studio/data-structures/index.md +++ b/docs/data-product-studio/data-structures/index.md @@ -8,4 +8,4 @@ This section explains how to create, manage, and update [data structures](/docs/ * Snowplow BDP Console UI * Data structures API * [Snowplow CLI](/docs/data-product-studio/snowplow-cli/index.md) -* For Community users: [Iglu](/docs/api-reference/iglu/iglu-repositories/iglu-server/) +* For Community users: [Iglu](/docs/api-reference/iglu/iglu-repositories/iglu-server/index.md) diff --git a/docs/data-product-studio/data-structures/manage/builder/images/data-structures-2.png b/docs/data-product-studio/data-structures/manage/builder/images/data-structures-2.png index 4a0fe317c0..047c2a8053 100644 Binary files a/docs/data-product-studio/data-structures/manage/builder/images/data-structures-2.png and b/docs/data-product-studio/data-structures/manage/builder/images/data-structures-2.png differ diff --git a/docs/data-product-studio/data-structures/manage/images/builder-or-json.png b/docs/data-product-studio/data-structures/manage/images/builder-or-json.png index 4cc16c92f7..df65b91817 100644 Binary files a/docs/data-product-studio/data-structures/manage/images/builder-or-json.png and b/docs/data-product-studio/data-structures/manage/images/builder-or-json.png differ diff --git a/docs/data-product-studio/data-structures/manage/images/image-1.png b/docs/data-product-studio/data-structures/manage/images/image-1.png index c7e60b0918..3bfff9fa19 100644 Binary files a/docs/data-product-studio/data-structures/manage/images/image-1.png and b/docs/data-product-studio/data-structures/manage/images/image-1.png differ diff --git a/docs/data-product-studio/data-structures/manage/json-editor/images/image-2.png b/docs/data-product-studio/data-structures/manage/json-editor/images/image-2.png index c4e6805120..7a979905a8 100644 Binary files a/docs/data-product-studio/data-structures/manage/json-editor/images/image-2.png and b/docs/data-product-studio/data-structures/manage/json-editor/images/image-2.png differ diff --git a/docs/data-product-studio/data-structures/version-amend/_breaking.md b/docs/data-product-studio/data-structures/version-amend/_breaking.md index 0bedfa9192..da5c824e19 100644 --- a/docs/data-product-studio/data-structures/version-amend/_breaking.md +++ b/docs/data-product-studio/data-structures/version-amend/_breaking.md @@ -4,7 +4,7 @@ There are two kinds of schema changes: Different data warehouses handle schema evolution slightly differently. Use the table below as a guide for incrementing the schema version appropriately. -
RedshiftSnowflake, BigQuery & Databricks
Add / remove / rename an optional fieldNon-breakingNon-breaking
Add / remove / rename a required fieldBreakingBreaking
Change a field from optional to requiredBreakingBreaking
Change a field from required to optionalBreakingNon-breaking
Change the type of an existing fieldBreakingBreaking
Change the size of an existing fieldNon-breakingNon-breaking
+
RedshiftSnowflake, BigQuery & Databricks
Add / remove / rename an optional fieldNon-breakingNon-breaking
Add / remove / rename a required fieldBreakingBreaking
Change a field from optional to requiredBreakingBreaking
Change a field from required to optionalBreakingNon-breaking
Change the type of an existing fieldBreakingBreaking
Change the size of an existing fieldNon-breakingNon-breaking
:::caution diff --git a/docs/data-product-studio/data-structures/version-amend/builder/images/data-structures-1.png b/docs/data-product-studio/data-structures/version-amend/builder/images/data-structures-1.png index 0535fd6d60..f40f6fbbfc 100644 Binary files a/docs/data-product-studio/data-structures/version-amend/builder/images/data-structures-1.png and b/docs/data-product-studio/data-structures/version-amend/builder/images/data-structures-1.png differ diff --git a/docs/data-product-studio/data-structures/version-amend/builder/images/data-structures-2.png b/docs/data-product-studio/data-structures/version-amend/builder/images/data-structures-2.png index 7ed1b060d3..56a6a4af95 100644 Binary files a/docs/data-product-studio/data-structures/version-amend/builder/images/data-structures-2.png and b/docs/data-product-studio/data-structures/version-amend/builder/images/data-structures-2.png differ diff --git a/docs/data-product-studio/data-structures/version-amend/builder/index.md b/docs/data-product-studio/data-structures/version-amend/builder/index.md index 34f595f249..f6228d0ff7 100644 --- a/docs/data-product-studio/data-structures/version-amend/builder/index.md +++ b/docs/data-product-studio/data-structures/version-amend/builder/index.md @@ -12,8 +12,6 @@ sidebar_custom_props: Versioning is automated when using the Data Structure Builder to create or edit your custom [Data Structures](/docs/fundamentals/schemas/index.md) for your [Events](/docs/fundamentals/events/index.md) and [Entities](/docs/fundamentals/entities/index.md). -![](images/data-structures-2.png) - **Breaking and non-breaking changes** At the point of publishing a data structure, there are two options for versioning: @@ -22,5 +20,5 @@ At the point of publishing a data structure, there are two options for versionin The Data Structure builder will automatically select how to version up your data structure depending on the changes you have just made. -![](images/data-structures-1.png) ![](images/data-structures-2.png) +![](images/data-structures-1.png) diff --git a/docs/data-product-studio/index.md b/docs/data-product-studio/index.md index 87322750f7..4005c95707 100644 --- a/docs/data-product-studio/index.md +++ b/docs/data-product-studio/index.md @@ -103,7 +103,7 @@ These include: * Error and performance tracking. It is recommended to use and build on top of these data structures in order to save effort and make use of the existing Snowplow dbt packages and tooling. -To get a comprehensive overview of the out-of-the-box provided schemas, [please refer to this page](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +To get a comprehensive overview of the out-of-the-box provided schemas, [please refer to this page](/docs/events/index.md). Our [data product accelerators](https://snowplow.io/data-product-accelerators/) are a great resource to develop your data product faster using out-of-the-box data structures based on best practices. diff --git a/docs/data-product-studio/snowtype/using-the-cli/images/dp-id.png b/docs/data-product-studio/snowtype/using-the-cli/images/dp-id.png index 327cc22a5d..867dc2e17b 100644 Binary files a/docs/data-product-studio/snowtype/using-the-cli/images/dp-id.png and b/docs/data-product-studio/snowtype/using-the-cli/images/dp-id.png differ diff --git a/docs/data-product-studio/snowtype/using-the-cli/images/dp-track.png b/docs/data-product-studio/snowtype/using-the-cli/images/dp-track.png index ac71072f6b..ed9ddbcd27 100644 Binary files a/docs/data-product-studio/snowtype/using-the-cli/images/dp-track.png and b/docs/data-product-studio/snowtype/using-the-cli/images/dp-track.png differ diff --git a/docs/data-product-studio/snowtype/using-the-cli/images/ds-url.png b/docs/data-product-studio/snowtype/using-the-cli/images/ds-url.png index 08f4c489bc..0aad5bbe77 100644 Binary files a/docs/data-product-studio/snowtype/using-the-cli/images/ds-url.png and b/docs/data-product-studio/snowtype/using-the-cli/images/ds-url.png differ diff --git a/docs/data-product-studio/snowtype/using-the-cli/images/es-id.png b/docs/data-product-studio/snowtype/using-the-cli/images/es-id.png index c20acfdc8f..455ad2b8fb 100644 Binary files a/docs/data-product-studio/snowtype/using-the-cli/images/es-id.png and b/docs/data-product-studio/snowtype/using-the-cli/images/es-id.png differ diff --git a/docs/data-product-studio/snowtype/using-the-cli/images/iglu-url.png b/docs/data-product-studio/snowtype/using-the-cli/images/iglu-url.png index c783232d7b..a91b30d7a0 100644 Binary files a/docs/data-product-studio/snowtype/using-the-cli/images/iglu-url.png and b/docs/data-product-studio/snowtype/using-the-cli/images/iglu-url.png differ diff --git a/docs/data-product-studio/source-applications/index.md b/docs/data-product-studio/source-applications/index.md index 1469a2d8e4..29a0b86ac5 100644 --- a/docs/data-product-studio/source-applications/index.md +++ b/docs/data-product-studio/source-applications/index.md @@ -26,7 +26,7 @@ Source Applications are a foundational component that enables you to establish t ## Application IDs -For each of these applications you would set up a unique application ID using the [app_id](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/app-information/index.md#atomic-event-properties) field to distinguish them later on in analysis. +For each of these applications you would set up a unique application ID using the [app_id](/docs/events/ootb-data/app-information/index.md#atomic-event-properties) field to distinguish them later on in analysis. :::tip We often see, and recommend as a best practice, setting up a unique application ID for each deployment environment you are using. For example `${appId}-qa` for staging, `${appId}-dev` for development environments. diff --git a/docs/destinations/forwarding-events/snowbridge/configuration/monitoring/index.md b/docs/destinations/forwarding-events/snowbridge/configuration/monitoring/index.md index fd10242515..049abd4e70 100644 --- a/docs/destinations/forwarding-events/snowbridge/configuration/monitoring/index.md +++ b/docs/destinations/forwarding-events/snowbridge/configuration/monitoring/index.md @@ -30,6 +30,14 @@ https://github.com/snowplow/snowbridge/blob/master/assets/docs/configuration/mon https://github.com/snowplow/snowbridge/blob/master/assets/docs/configuration/monitoring/statsd-example.hcl ``` +### End-to-end latency configuration + +Snowplow Enriched data only: + +```hcl reference +https://github.com/snowplow/snowbridge/blob/master/assets/docs/configuration/metrics/e2e-latency-example.hcl +``` + Snowbridge sends the following metrics to statsd: | Metric | Definitions | @@ -54,3 +62,6 @@ Snowbridge sends the following metrics to statsd: | `min_request_latency` | Min time between starting request to target and finishing request to target. | | `max_request_latency` | Max time between starting request to target and finishing request to target. | | `avg_request_latency` | Avg time between starting request to target and finishing request to target. | +| `min_e2e_latency` | Min time between Snowplow collector tstamp and finishing request to target. Enabled via configuration - Snowplow enriched data only. | +| `max_e2e_latency` | Max time between Snowplow collector tstamp and finishing request to target. Enabled via configuration - Snowplow enriched data only. | +| `avg_e2e_latency` | Avg time between Snowplow collector tstamp and finishing request to target. Enabled via configuration - Snowplow enriched data only. | diff --git a/docs/events/cookie-extension/index.md b/docs/events/cookie-extension/index.md new file mode 100644 index 0000000000..001987d658 --- /dev/null +++ b/docs/events/cookie-extension/index.md @@ -0,0 +1,122 @@ +--- +title: "Cookie Extension service" +description: "How to create and use a Cookie Extension service, previously known as ID service, to mitigate against ITP" +date: "2020-02-26" +sidebar_position: 3.5 +--- + +A Cookie Extension service works with the Snowplow [browser tracker](/docs/sources/trackers/javascript-trackers/web-tracker/index.md) to help you maintain consistent user identification despite browser privacy restrictions like Safari's Intelligent Tracking Prevention. + +Deployed within your website's IP space, the service creates and manages persistent browser identifiers. + +## Why use a Cookie Extension service? + +Browsers, including iOS browsers (Safari, Chrome, Firefox) and desktop Safari, have limited the lifetime of some cookies, which limits the effectiveness of tracking a customer journey where the user is not regularly returning to your website. + +As of Safari 16.4, released in April 2023, Safari sets the [lifetime of server-set first-party cookies](https://webkit.org/tracking-prevention/#cname-and-third-party-ip-address-cloaking-defense) to a maximum of 7 days in the following cases: + +1. The server setting the cookie is behind a CNAME that resolves (at any point) to a host that is third-party to the website the user is currently browsing. +2. The server setting the cookie is set with A/AAAA records that resolve to an IP address (IP4 or IP6) where the first half of the address does not match the first half of the IP address for the server on the website the user is currently browsing. (e.g. 203.52.1.2 and 203.52.56.22 are okay, 201.55.1.2 is not). + +By using a Cookie Extension service, you can extend the lifetime of browser identifiers, and therefore maintain high-quality knowledge of your customer journeys. + +## Using the service + +You will need to deploy and execute your Cookie Extension service code from the same IP space that serves the main web document of your application. This is probably the web application system, or the CDN in front of the application. + +This code has minimal functionality and could be: + +- An **API endpoint** that is part of the main web application. +- **A function running in an edge worker.** Almost all modern CDNs allow the addition of 'middleware' code which runs on requests at edge nodes in front of the client's application domain. +- **A custom middleware based on the customer's framework**, e.g. ExpressJS middleware, Next.js middleware, Play custom action etc. that can run on every document request. +- **A low-footprint application with a single endpoint**, e.g. a Go web server. + +```mermaid +sequenceDiagram + autonumber + participant Service as Cookie Extension service endpoint + participant Tracking as Snowplow tracking code + participant Collector as Snowplow Collector + Tracking->>Service: Request an ID + note over Service: Cookie Extension service code + Service->>Tracking: OK response + note over Tracking,Service: Set-Cookie: sp=...
Set-Cookie: spCookieExtensionService=... + loop Normal flow + Tracking->>Collector: Event tracking + note over Tracking,Collector: Cookie: sp=...#59; spCookieExtensionService=... + end +``` + +## Developing the service + +The responsibilities of this service are: +1. Create a unique identifier (UUID v4) for this browser, set it in a cookie and return it in a `Set-Cookie` response header on a domain accessible by the service at all times. +2. Increase the expiry for the cookie used as the network_userid identifier (by default, a cookie named `sp`, configured via `collector.config.name`) which should have the same value as the first cookie. + +On this page, we've called the new unique identifier cookie `spCookieExtensionService`. + +### Business logic + +The Cookie Extension service code should include the following logic: + +- If the Cookie Extension service new identifier cookie already exists on the request, then it should re-set the cookies with the same values and updated expiration for both the `spCookieExtensionService` and `sp` cookies. +- If `spCookieExtensionService` does not exist, but the collector's `sp` cookie does exist, then the it should set `spCookieExtensionService value = sp cookie value`. _This will make sure we keep old identifiers in place and not lose any data._ +- If `spCookieExtensionService` and `sp` are both missing, then it generates a new ID in the `spCookieExtensionService` 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. + +### Example code + +Here are two examples of code for Cookie Extension service API endpoints. + + + + +```ts reference +https://github.com/snowplow-industry-solutions/cookie-extension-service-examples/blob/main/examples/typescript/Next.js/api-route.ts +``` + + + + +```php reference +https://github.com/snowplow-industry-solutions/cookie-extension-service-examples/blob/main/examples/php/wordpress/api-route.php +``` + + + + + +## Configuring the browser tracker + +:::note +Before version 4.5.0 of the tracker this attribute was available as `idService`. +::: + +When the Cookie Extension service has been deployed on a system with the same resolved IP as the main document, the tracker can then be configured to orchestrate the required Cookie Extension service API calls. + +This process is opt-in by using the `cookieExtensionService` option during tracker initialization: + + + + +```tsx +window.snowplow("newTracker", "sp", "{{collector_url_here}}", { + /* ...Rest of the tracker options */ + cookieExtensionService: "/cookie-extension-service-endpoint" +}); +``` + + + + +```tsx +newTracker('sp1', 'c.customer.com', { + cookieExtensionService: "/cookie-extension-service-endpoint", + /* ...Rest of the tracker options */ + }); +``` + + + + +When the tracker detects this option it will send an HTTP request during initialization on this endpoint to have the service set the required identifiers before sending any event. diff --git a/docs/sources/trackers/snowplow-tracker-protocol/custom-events/context-entities/index.md b/docs/events/custom-events/context-entities/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/custom-events/context-entities/index.md rename to docs/events/custom-events/context-entities/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/custom-events/index.md b/docs/events/custom-events/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/custom-events/index.md rename to docs/events/custom-events/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/custom-events/self-describing-events/index.md b/docs/events/custom-events/self-describing-events/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/custom-events/self-describing-events/index.md rename to docs/events/custom-events/self-describing-events/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/custom-events/structured-events/index.md b/docs/events/custom-events/structured-events/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/custom-events/structured-events/index.md rename to docs/events/custom-events/structured-events/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/going-deeper/event-parameters/index.md b/docs/events/going-deeper/event-parameters/index.md similarity index 97% rename from docs/sources/trackers/snowplow-tracker-protocol/going-deeper/event-parameters/index.md rename to docs/events/going-deeper/event-parameters/index.md index e2d2f69b7a..a852debe9c 100644 --- a/docs/sources/trackers/snowplow-tracker-protocol/going-deeper/event-parameters/index.md +++ b/docs/events/going-deeper/event-parameters/index.md @@ -2,7 +2,7 @@ title: "Event parameters" --- -This page lists all the parameters that Snowplow trackers use when firing events to push data into the Snowplow collectors. Each parameter maps onto one or more fields in the Snowplow events table employed in storage. +This page lists all the parameters that Snowplow trackers use when firing events to push data into the Snowplow collectors. Each parameter maps onto one or more fields in the Snowplow events table employed in storage. This page is for you if you want to understand the tracker payload in more detail, and especially if you are building your own tracker. In the latter case, utilizing the parameters documented here will ensure that your tracker works with the rest of the Snowplow stack. @@ -42,7 +42,7 @@ Additionally, [entities can be attached to events](#event-entity-tracking) which [Structuring your data with schemas](/docs/fundamentals/schemas/index.md) to perform self-describing event tracking is the defacto way to track events with Snowplow and allows any arbitrary name: value pairs to be captured with the event. -To learn about self-describing events and how they are serialized in the tracker payload, [visit this page](/docs/sources/trackers/snowplow-tracker-protocol/custom-events/self-describing-events/index.md). +To learn about self-describing events and how they are serialized in the tracker payload, [visit this page](/docs/events/custom-events/self-describing-events/index.md). ### Other Events @@ -122,7 +122,7 @@ As well as setting `e=se`, there are five custom event specific parameters that ### Event Entity Tracking Custom entities can be used to add additional context to an event. -To learn about context entities and how they are serialized in the event payload, [visit this page](/docs/sources/trackers/snowplow-tracker-protocol/custom-events/context-entities/index.md). +To learn about context entities and how they are serialized in the event payload, [visit this page](/docs/events/custom-events/context-entities/index.md). ## Common Parameters @@ -184,9 +184,9 @@ The tracker namespace parameter is used to distinguish between different tracker :::info -The Snowplow Collector will also capture `collector_tstamp` which the time the event arrived at the collector. +The Snowplow Collector will also capture `collector_tstamp` which the time the event arrived at the Collector. -Snowplow will also calculate a `derived_tstamp` which attempts to make allowances for innaccurate device clocks. +Snowplow will also calculate a `derived_tstamp` which attempts to make allowances for inaccurate device clocks. The `ttm` field is used for a timestamp set on the client which should be taken as accurate. This will overwrite the `derived_tstamp` if set. ::: diff --git a/docs/sources/trackers/snowplow-tracker-protocol/going-deeper/example-requests/index.md b/docs/events/going-deeper/example-requests/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/going-deeper/example-requests/index.md rename to docs/events/going-deeper/example-requests/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/going-deeper/http-headers/index.md b/docs/events/going-deeper/http-headers/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/going-deeper/http-headers/index.md rename to docs/events/going-deeper/http-headers/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/going-deeper/index.md b/docs/events/going-deeper/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/going-deeper/index.md rename to docs/events/going-deeper/index.md diff --git a/docs/events/index.md b/docs/events/index.md new file mode 100644 index 0000000000..c093e90ce4 --- /dev/null +++ b/docs/events/index.md @@ -0,0 +1,60 @@ +--- +title: "Events" +description: "" +date: "2020-02-26" +sidebar_position: 3.5 +--- + +# Snowplow event specification + +At its heart, Snowplow is a platform for granular tracking of events. +Snowplow trackers fire _events_, which are either HTTP GET or POST requests to a Snowplow collector. By adding parameters to these requests, trackers can pass data into the collector for processing by Snowplow. + +This section aims to give an overview of Snowplow events. +It lists the available data types and links to the tracking and modeling documentation for them. +If you are interested in an overview of the properties in the atomic events table, [please refer to this page](/docs/fundamentals/canonical-event/index.md). + +## Custom events and context entities + +Snowplow data is designed to be able to tailor to your business needs using custom events and context entities. + +| Category | Description | +| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | +| [Context entities](/docs/events/custom-events/context-entities/index.md) | Add information to events using reusable entities. | +| [Self-describing events](/docs/events/custom-events/self-describing-events/index.md) | Track custom events with schemas. | +| [Structured events](/docs/events/custom-events/structured-events/index.md) | Track custom events without schemas (not recommended – we recommend tracking self-describing events instead). | + +## Out-of-the-box data + +Snowplow also provides out-of-the-box events, context entities and atomic event properties for common Web and mobile use cases. + +| Category | Description | +| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | +| [Page and screen view events](/docs/events/ootb-data/page-and-screen-view-events/index.md) | Basic building block for tracking views of Web pages or mobile screens. | +| [Page activity events](/docs/events/ootb-data/page-activity-tracking/index.md) | Tracking user engagement on the Web page using page pings. | +| [Mobile app lifecycle events](/docs/events/ootb-data/mobile-lifecycle-events/index.md) | Events to track mobile app lifecycle (install, going to foreground, background). | +| [Referrers, deep links and cross-navigation events](/docs/events/ootb-data/links-and-referrers/index.md) | Events and properties to track referrer information and linking between apps and websites. | +| [App error events](/docs/events/ootb-data/app-error-events/index.md) | Tracking errors and exceptions from apps. | +| [Consent events](/docs/events/ootb-data/consent-events/index.md) | Events for tracking user consent. | +| [E-commerce events](/docs/events/ootb-data/ecommerce-events/index.md) | Events for tracking e-commerce transactions and more. | +| [Media events](/docs/events/ootb-data/media-events/index.md) | Tracking media playback in Web or mobile apps. | +| [Performance metrics](/docs/events/ootb-data/app-performance/index.md) | Events to track performance metrics from websites and apps. | +| [App information](/docs/events/ootb-data/app-information/index.md) | Information about the app that the events originate from. | +| [Device and browser information](/docs/events/ootb-data/device-and-browser/index.md) | Information about the device or browser of the user. | +| [User and session identification and stitching](/docs/events/ootb-data/user-and-session-identification/index.md) | Overview of the user and session identifiers provided by the trackers and how to stitch them. | +| [Geolocation information](/docs/events/ootb-data/geolocation/index.md) | Geolocation information attached to events. | + +
+ Going deeper into the event properties +
+ +These pages are for you if you want to understand the tracker payload in more detail, and especially if you are building your own tracker. In the latter case, utilizing the parameters documented here will ensure that your tracker works with the rest of the Snowplow stack. + +| Category | Description | +| ----------------------------------------------------------------------- | ---------------------------------------------------- | +| [Event parameters](/docs/events/going-deeper/event-parameters/index.md) | Protocol of all the parameters in the event payload. | +| [HTTP headers](/docs/events/going-deeper/http-headers/index.md) | Collecting HTTP request headers and cookies. | +| [Example requests](/docs/events/going-deeper/example-requests/index.md) | Example tracker requests with sample payload. | + +
+
diff --git a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/app-error-events/index.md b/docs/events/ootb-data/app-error-events/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/ootb-data/app-error-events/index.md rename to docs/events/ootb-data/app-error-events/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/app-information/index.md b/docs/events/ootb-data/app-information/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/ootb-data/app-information/index.md rename to docs/events/ootb-data/app-information/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/app-performance/index.md b/docs/events/ootb-data/app-performance/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/ootb-data/app-performance/index.md rename to docs/events/ootb-data/app-performance/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/consent-events/index.md b/docs/events/ootb-data/consent-events/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/ootb-data/consent-events/index.md rename to docs/events/ootb-data/consent-events/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/device-and-browser/index.md b/docs/events/ootb-data/device-and-browser/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/ootb-data/device-and-browser/index.md rename to docs/events/ootb-data/device-and-browser/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/ecommerce-events/index.md b/docs/events/ootb-data/ecommerce-events/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/ootb-data/ecommerce-events/index.md rename to docs/events/ootb-data/ecommerce-events/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/geolocation/index.md b/docs/events/ootb-data/geolocation/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/ootb-data/geolocation/index.md rename to docs/events/ootb-data/geolocation/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/index.md b/docs/events/ootb-data/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/ootb-data/index.md rename to docs/events/ootb-data/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/links-and-referrers/index.md b/docs/events/ootb-data/links-and-referrers/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/ootb-data/links-and-referrers/index.md rename to docs/events/ootb-data/links-and-referrers/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/media-events/index.md b/docs/events/ootb-data/media-events/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/ootb-data/media-events/index.md rename to docs/events/ootb-data/media-events/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md b/docs/events/ootb-data/mobile-lifecycle-events/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md rename to docs/events/ootb-data/mobile-lifecycle-events/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md b/docs/events/ootb-data/page-activity-tracking/index.md similarity index 98% rename from docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md rename to docs/events/ootb-data/page-activity-tracking/index.md index a59dc27238..d024661829 100644 --- a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md +++ b/docs/events/ootb-data/page-activity-tracking/index.md @@ -36,7 +36,7 @@ Screen engagement tracking is available for native Android and iOS apps starting Screen engagement information is tracked on our mobile trackers in the `screen_summary` context entity. The entity is tracked along with these events: -1. `application_foreground` and `application_background` events (see [lifecycle events](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md)). +1. `application_foreground` and `application_background` events (see [lifecycle events](/docs/events/ootb-data/mobile-lifecycle-events/index.md)). 2. `screen_end` event (see below). ### Screen summary entity diff --git a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-and-screen-view-events/index.md b/docs/events/ootb-data/page-and-screen-view-events/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-and-screen-view-events/index.md rename to docs/events/ootb-data/page-and-screen-view-events/index.md diff --git a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/user-and-session-identification/index.md b/docs/events/ootb-data/user-and-session-identification/index.md similarity index 96% rename from docs/sources/trackers/snowplow-tracker-protocol/ootb-data/user-and-session-identification/index.md rename to docs/events/ootb-data/user-and-session-identification/index.md index 8924a0f16b..a870370493 100644 --- a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/user-and-session-identification/index.md +++ b/docs/events/ootb-data/user-and-session-identification/index.md @@ -23,7 +23,7 @@ In the tracked events, it can appear either: * This is currently the default behavior on Web apps. * It is not supported in mobile apps. * This is referred to as the default `user_identifier` field in the dbt-snowplow-unified package -2. As the `userId` property in the `client_session` context entity ([see below](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/user-and-session-identification/index.md#client-session-context-entity)). +2. As the `userId` property in the `client_session` context entity ([see below](/docs/events/ootb-data/user-and-session-identification/index.md#client-session-context-entity)). * This is an optional configuration in the JavaScript tracker for Web apps. * It is the default behavior on mobile apps. * This is referred to as the default `user_identifier` field in the dbt-snowplow-unified package (used to be referred to as `device_user_id` in our legacy dbt-snowplow-mobile package). @@ -39,7 +39,7 @@ In case you want to change the default tracking behavior, refer to the following * Session tracking on mobile apps [using the iOS and Android trackers](/docs/sources/trackers/mobile-trackers/tracking-events/session-tracking/index.md) or [using the React Native tracker](/docs/sources/trackers/react-native-tracker/tracking-events/session-tracking/index.md). :::note -In mobile apps, there are additional on-device identifiers provided by the platform – advertising ID (IDFA) and vendor ID (IDFV, app set ID). These can be tracked [in the mobile context entity](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/device-and-browser/index.md#mobile-context). +In mobile apps, there are additional on-device identifiers provided by the platform – advertising ID (IDFA) and vendor ID (IDFV, app set ID). These can be tracked [in the mobile context entity](/docs/events/ootb-data/device-and-browser/index.md#mobile-context). ::: ### Server (Collector) generated user identifier @@ -48,7 +48,7 @@ The Snowplow Collector generates a user identifier that is stored in cookies for The identifier is available both in Web and mobile apps. However, in Android apps, it is stored in memory so it is reset after the app restarts. -In most scenarios, this identifier may have a longer lifetime than the tracker generated identifier. However, browsers can restrict it's lifetime for different reasons, such as when the Snowplow Collector is on a third-party domain from the website (not recommended), or due to the ITP restrictions in Safari (Snowplow provides a solution to mitigate this problem – [the ID service](/docs/sources/trackers/javascript-trackers/web-tracker/browsers/index.md#itp-mitigation)). +In most scenarios, this identifier may have a longer lifetime than the tracker generated identifier. However, browsers can restrict it's lifetime for different reasons, such as when the Snowplow Collector is on a third-party domain from the website (not recommended), or due to the ITP restrictions in Safari (Snowplow provides a solution to mitigate this problem – [the Cookie Extension service](/docs/events/cookie-extension/index.md)). :::info `network_userid` is captured via a cookie set by the Snowplow Collector. It can be overriden by setting `tnuid` on a Tracker request payload but is typically expected to be populated by the Collector cookies. @@ -112,7 +112,7 @@ In settings where multiple users share the same browser, identity stitching may Because the tracker generated user identifier will be consistent for all sessions from the browser, the stitched user identifier will also be consistent regardless of whether one or more users log in. In case you want to make sure that after a user logs out, the following events won't be attributed to the same user ID, you can reset the user and session identifiers in the tracker. -To do this on the JavaScript tracker, make use of the function to [clear user data](/docs/sources/trackers/javascript-trackers/web-tracker/anonymous-tracking/index.md#clear-user-data) +To do this on the JavaScript tracker, make use of the function to [clear user data](/docs/sources/trackers/javascript-trackers/web-tracker/anonymous-tracking/index.md#clear-user-data) (such a feature is not yet available on the mobile trackers). Clearing the user data on the tracker will result in new tracker generated user and session identifiers. It will not clear the server generated `network_userid` user identifier. diff --git a/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/visionos-swiftui/index.md b/docs/events/ootb-data/visionos-swiftui/index.md similarity index 100% rename from docs/sources/trackers/snowplow-tracker-protocol/ootb-data/visionos-swiftui/index.md rename to docs/events/ootb-data/visionos-swiftui/index.md diff --git a/docs/events/timestamps/index.md b/docs/events/timestamps/index.md new file mode 100644 index 0000000000..42d28871b2 --- /dev/null +++ b/docs/events/timestamps/index.md @@ -0,0 +1,45 @@ +--- +title: "Timestamps" +description: "" +date: "2025-05-15" +sidebar_position: 4 +--- + +Snowplow events have multiple timestamps that are added as the payload moves through the pipeline. The set of timestamps is designed to account for devices with incorrectly set clocks, or delays in event sending due to network outages. + +The timestamps are: + +| Timestamp | Added by | Description | In all events | +| --------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | +| `dvce_created_tstamp` | [Tracker](/docs/sources/trackers/index.md) | The device's timestamp when the event was created - not necessarily the correct time | ✅ | +| `dvce_sent_tstamp` | [Tracker](/docs/sources/trackers/index.md) | The device's timestamp when the event was successfully sent to the Collector endpoint - not necessarily the correct time | ✅ | +| `true_tstamp` | You | Exact timestamp, defined within your tracking code | ❌ | +| `collector_tstamp` | [Collector](/docs/pipeline/collector/index.md) | When the Collector received the event payload | ✅ | +| `derived_tstamp` | [Enrich](/docs/api-reference/enrichment-components/index.md) | Calculated from other timestamps, or the same as `true_tstamp` | ✅ | +| `etl_tstamp` | [Enrich](/docs/api-reference/enrichment-components/index.md) | The time at which Enrich started processing the event | ✅ | +| `refr_device_tstamp` | [Enrich](/docs/api-reference/enrichment-components/index.md) | Timestamp extracted from the [cross-domain navigation query string](/docs/pipeline/enrichments/available-enrichments/cross-navigation-enrichment/index.md), if present | ❌ | +| `load_tstamp` | [Loader](/docs/destinations/warehouses-lakes/loading-process/index.md) or warehouse | Timestamp when the event was loaded into the warehouse | ✅ | + +The `load_tstamp` is added either by the Loader or by the warehouse at the point of loading, depending on the Loader/warehouse. Use this timestamp for incremental processing. + +## Derived timestamp + +The `derived_tstamp` corrects for inaccurate timestamps and delays. + +It's calculated as `collector_tstamp` minus the difference between the `dvce_sent_tstamp` and the `dvce_created_tstamp`. Alternatively, if `true_tstamp` is available, `derived_tstamp` is the same as `true_tstamp`. + +The calculation has two assumptions: +* We assume that, although `dvce_created_tstamp` and `dvce_sent_tstamp` can both be inaccurate, they're inaccurate in precisely the same way. If the device clock is 15 minutes fast at event creation, then it remains 15 minutes fast at event sending, whenever that might be. +* We assume that the time taken for an event to get from the device to the Collector is neglible, i.e. the lag between `dvce_sent_tstamp` and `collector_tstamp` is 0 seconds. + +## What timestamp to use? + +The choice of timestamp for downstream analysis depends on how you're using the data. + +For reporting, we recommend using the `derived_tstamp`. Our data models use `derived_tstamp` as the default `start_tstamp` for creating derived tables. + +To filter the `atomic.events` table directly, use the timestamp it's partitioned on. For example, if your warehouse is partitioned by `load_tstamp`, then use clauses like `WHERE load_tstamp > ?` in your analysis. + +The `refr_device_tstamp` timestamp can help you understand cross-domain navigation by your users. + +All of the timestamps can also be used for custom use cases, or in debugging, to closely follow how the events are created and move through the pipeline. diff --git a/docs/fundamentals/canonical-event/index.md b/docs/fundamentals/canonical-event/index.md index 56b42e9c0a..6aa6cbe637 100644 --- a/docs/fundamentals/canonical-event/index.md +++ b/docs/fundamentals/canonical-event/index.md @@ -141,7 +141,7 @@ Some Snowplow Trackers allow the user to name each specific Tracker instance. `n `domain_sessionidx` is the number of the current user session. For example, an event occurring during a user's first session would have `domain_sessionidx` set to 1. The JavaScript Tracker calculates this field by storing a visit count in a first-party cookie. Whenever the Tracker fires an event, if more than 30 minutes have elapsed since the last event, the visitor count is increased by 1. (Whenever an event is fired, a "session cookie" is created and set to expire in 30 minutes. This is how the Tracker can tell whether the visit count should be incremented.) Thirty minutes is the default value and can be changed using the `sessionCookieTimeout` configuration option in the tracker. -It is worth to call out here that the `domain_userid` is regarded as the most reliable session based identifier for most use cases, it is therefore treated as the primary `user_identifier` field in our data models that rely on sessionisation (e.g. the Unified data model). These are only populated for web events, the mobile equivalent is embedded into an ootb entity called [Session Context Entity](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/user-and-session-identification/index.md#client-session-context-entity) which are then extracted (`session__user_id`) then coalesced with the web based domain_userid by default and being referred to as `user_identifier` within the data modeling package. +It is worth to call out here that the `domain_userid` is regarded as the most reliable session based identifier for most use cases, it is therefore treated as the primary `user_identifier` field in our data models that rely on sessionisation (e.g. the Unified data model). These are only populated for web events, the mobile equivalent is embedded into an ootb entity called [Session Context Entity](/docs/events/ootb-data/user-and-session-identification/index.md#client-session-context-entity) which are then extracted (`session__user_id`) then coalesced with the web based domain_userid by default and being referred to as `user_identifier` within the data modeling package. #### Device and operating system fields @@ -156,7 +156,7 @@ It is worth to call out here that the `domain_userid` is regarded as the most re | os_family | text| Operating system family| No| 'Linux'| Deprecated | ✅ | ✅ | | os_manufacturer | text| Company responsible for OS | No| 'Apple'| Deprecated | ✅ | ✅ | -For more information on this topic please check out the relevant [Tracking Documentation](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/device-and-browser/index.md). +For more information on this topic please check out the relevant [Tracking Documentation](/docs/events/ootb-data/device-and-browser/index.md). #### Location fields | Field | Type | Description | Reqd? | Example| Source| Web | Mobile| @@ -170,7 +170,7 @@ For more information on this topic please check out the relevant [Tracking Docum | geo_region_name | text | Visitor region name | No| 'Florida'| [IP Enrichment](/docs/pipeline/enrichments/available-enrichments/ip-lookup-enrichment/index.md) | ✅ | ✅ | | geo_timezone| text | Visitor timezone name | No| 'Europe/London'| [IP Enrichment](/docs/pipeline/enrichments/available-enrichments/ip-lookup-enrichment/index.md) | ✅ | ✅ | -For more information on this topic please check out the relevant [Tracking Documentation](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/geolocation/index.md). +For more information on this topic please check out the relevant [Tracking Documentation](/docs/events/ootb-data/geolocation/index.md). #### IP address-based fields @@ -265,7 +265,7 @@ Fields containing information about the event type. | br_viewheight | int | Viewport height| No| 1000 | Tracking | ✅ | ❌ | | `br_viewwidth`| int | Viewport width | No| 1000 | Tracking| ✅ | ❌ | -For more information on this topic please check out the relevant [Tracking Documentation](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/device-and-browser/index.md). +For more information on this topic please check out the relevant [Tracking Documentation](/docs/events/ootb-data/device-and-browser/index.md). ### Event-specific fields @@ -333,7 +333,7 @@ Fields that start `tr_` relate to the transaction as a whole. Fields that start \* Set exclusively by the [Currency conversion enrichment](/docs/pipeline/enrichments/available-enrichments/currency-conversion-enrichment/index.md). -For more information on this topic please check out the relevant [Tracking Documentation](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/ecommerce-events/index.md). +For more information on this topic please check out the relevant [Tracking Documentation](/docs/events/ootb-data/ecommerce-events/index.md). #### Structured events @@ -350,7 +350,7 @@ For more information on this topic please check out the relevant [Tracking Docum \* These fields are only required for `struct` events. -For more information on this topic please check out the relevant [Tracking Documentation](/docs/sources/trackers/snowplow-tracker-protocol/custom-events/structured-events/index.md). +For more information on this topic please check out the relevant [Tracking Documentation](/docs/events/custom-events/structured-events/index.md). #### Self-describing events @@ -361,7 +361,7 @@ For each type of self-describing event, there will be a dedicated column (or tab See [querying data](/docs/destinations/warehouses-lakes/querying-data/index.md#self-describing-events) for more details on the structure and how to query it in different warehouses. You might also want to check [how schema definitions translate to the warehouse](/docs/destinations/warehouses-lakes/schemas-in-warehouse/index.md). -For more information on this topic please check out the relevant [Tracking Documentation](/docs/sources/trackers/snowplow-tracker-protocol/custom-events/self-describing-events/index.md). +For more information on this topic please check out the relevant [Tracking Documentation](/docs/events/custom-events/self-describing-events/index.md). #### Entities @@ -371,7 +371,7 @@ For each type of entity, there will be a dedicated column (or table, in case of See [querying data](/docs/destinations/warehouses-lakes/querying-data/index.md#entities) for more details on the structure and how to query it in different warehouses. You might also want to check [how schema definitions translate to the warehouse](/docs/destinations/warehouses-lakes/schemas-in-warehouse/index.md). -For more information on this topic please check out the relevant [Tracking Documentation](/docs/sources/trackers/snowplow-tracker-protocol/custom-events/context-entities/index.md). +For more information on this topic please check out the relevant [Tracking Documentation](/docs/events/custom-events/context-entities/index.md). ### Out-of-the-box self-describing events and entities diff --git a/docs/fundamentals/data-products/images/example_data_product_view.png b/docs/fundamentals/data-products/images/example_data_product_view.png new file mode 100644 index 0000000000..090378836e Binary files /dev/null and b/docs/fundamentals/data-products/images/example_data_product_view.png differ diff --git a/docs/fundamentals/data-products/images/example_event_specification.png b/docs/fundamentals/data-products/images/example_event_specification.png new file mode 100644 index 0000000000..304c6bc094 Binary files /dev/null and b/docs/fundamentals/data-products/images/example_event_specification.png differ diff --git a/docs/fundamentals/data-products/images/key-elements-of-a-data-product.png b/docs/fundamentals/data-products/images/key-elements-of-a-data-product.png deleted file mode 100644 index b757b040f4..0000000000 Binary files a/docs/fundamentals/data-products/images/key-elements-of-a-data-product.png and /dev/null differ diff --git a/docs/fundamentals/data-products/index.md b/docs/fundamentals/data-products/index.md index 0862aa7a6a..49ede6a34f 100644 --- a/docs/fundamentals/data-products/index.md +++ b/docs/fundamentals/data-products/index.md @@ -38,6 +38,8 @@ Examples of data products: **The Source Application/s it is part of**; a data product is referencing the [Source Application/s](/docs/data-product-studio/source-applications/index.md) that is spanning across. +![Example Data Product view](images/example_data_product_view.png) + **Benefits:** * Have a clear view in which application the data product is implemented in, which domains it spans and the related application context information it will have available by default in the dataset. @@ -50,6 +52,8 @@ Examples of data products: **Event specifications**; these describe each event that is collected as part of the data product, on which applications they are triggered and where, the event data structure to validate against, and the entities to attach to each event (e.g. user, product etc). +![Example Event Specification](images/example_event_specification.png) + **Benefits:** * Provide implementation details to developers implementing tracking (see section on [Snowtype](/docs/data-product-studio/snowtype/index.md) for further details) @@ -70,8 +74,6 @@ Break down the barriers that exist between data producers and data consumers, by * Enhances accountability and transparency by providing a clear audit trail of all data modifications, fostering confidence in data integrity -![Key elements of a Data Product](images/key-elements-of-a-data-product.png) - **Volume metrics**; data products can detect events ingested in your pipeline that match the configured event specifications. This allows your team to monitor occurrence-related metrics for events being tracked with specific [event specification IDs](/docs/data-product-studio/snowtype/commands/index.md#snowtype-patch). **Benefits:** diff --git a/docs/fundamentals/schemas/index.md b/docs/fundamentals/schemas/index.md index 3a7b881638..0d5bbebfb1 100644 --- a/docs/fundamentals/schemas/index.md +++ b/docs/fundamentals/schemas/index.md @@ -117,7 +117,7 @@ After the self section, the remainder of the schema is where you will begin desc **“properties”** - Here is where you will describe the fields you intend on collecting. Each field is given a name and a number of arguments, these are important as they feed directly into the validation process. - **“description”** - Similar to the description field for the schema, this argument is where you should put detailed information on what this field represents to avoid any misunderstanding or misinterpretation during analysis. -- **"type"** - This denotes the type of data that is collected through this field. The most common types of data collected are `string`, `number`, `integer`, `object`, `array`, `boolean` and `null`. A single field can allow multiple types as shown in the field `job title` in the example schema which allows both `string` and `null` +- **"type"** - This denotes the type of data that is collected through this field. The most common types of data collected are `string`, `number`, `integer`, `object`, `array`, `boolean` and `null`. A single field can allow multiple types as shown in the field `job role` in the example schema which allows both `string` and `null` - Validation arguments can then be passed into the field such as `minLength`, `maxLength` and `enum` for strings and `minimum` and `maximum` for integers. A full set of valid arguments can be found on the [JSON schema specification](https://datatracker.ietf.org/doc/html/draft-fge-json-schema-validation-00#section-5). **“$supersedes”** / **“$supersededBy”** - _Optional, not shown_. See [marking schemas as superseded](/docs/data-product-studio/data-structures/version-amend/amending/index.md#marking-the-schema-as-superseded). diff --git a/docs/get-started/feature-comparison/index.md b/docs/get-started/feature-comparison/index.md index 6ec39f25c3..65214cb0dd 100644 --- a/docs/get-started/feature-comparison/index.md +++ b/docs/get-started/feature-comparison/index.md @@ -5,15 +5,15 @@ hide_table_of_contents: true sidebar_label: "Feature comparison" --- -Below you can find a detailed list of product features, including which are available as part of the Snowplow Behavioral Data Platform (BDP) and which are available with the [Snowplow Community Edition](/docs/get-started/snowplow-community-edition/index.md). +Here is a detailed list of product features, including which are available as part of the Snowplow Behavioral Data Platform (BDP) or [Snowplow Community Edition](/docs/get-started/snowplow-community-edition/index.md). |

Data Pipeline

| BDP | [Community Edition](/docs/get-started/snowplow-community-edition/index.md) | | :------------------------------------------------------------------------------------------------------------------------ | :---: | :------------------------------------------------------------------------: | -| [35+ trackers & webhooks](/docs/sources/index.md) | ✅ | ✅ | -| 1st party tracking | ✅ | ✅ | +| [35+ trackers and webhooks](/docs/sources/index.md) | ✅ | ✅ | +| First party tracking | ✅ | ✅ | | [Anonymous data collection](/docs/resources/recipes-tutorials/recipe-anonymous-tracking/index.md) | ✅ | ✅ | -| [ID service](/docs/sources/trackers/javascript-trackers/web-tracker/browsers/index.md#what-is-an-id-service) | ✅ | ✅ | -| High availability & auto-scaling | ✅ | ❌ | +| [Cookie Extension service](/docs/events/cookie-extension/index.md) | ✅ | ✅ | +| High availability and auto-scaling | ✅ | ❌ | | [Enrichments](/docs/pipeline/enrichments/available-enrichments/index.md) | ✅ | ✅ | | [Failed events](/docs/fundamentals/failed-events/index.md) | ✅ | ✅ | | [Data quality monitoring](/docs/data-product-studio/data-quality/failed-events/monitoring-failed-events/index.md) | ✅ | ❌ | @@ -28,37 +28,40 @@ Below you can find a detailed list of product features, including which are avai | • Synapse Analytics | ✅ | ✅ | | • Elasticsearch | ✅ | ✅ | | • S3 | ✅ | ✅ | -| • GCS | ✅ | ✅ | -| • ADLS / OneLake | ✅ | ✅ | +| • Google Cloud Storage | ✅ | ✅ | +| • Azure Data Lake Storage / OneLake | ✅ | ✅ | | **Real-time streams** | | | • Kinesis | ✅ | ✅ | -| • Pubsub | ✅ | ✅ | +| • PubSub | ✅ | ✅ | | • Kafka / Azure Event Hubs / Confluent Cloud | ✅ | ✅ | |

Data Product Studio

| BDP | [Community Edition](/docs/get-started/snowplow-community-edition/index.md) | -| Advanced enrichments (PII, IP anonymisation, JS, API, SQL enrichments) | ✅ | ✅ (no UI or API) | -| [Data structures tooling & API](/docs/data-product-studio/data-structures/manage/index.md) | ✅ | ❌ | -| [Data Products](/docs/data-product-studio/data-products/index.md) | ✅ | ❌ | +| Advanced enrichments (PII, IP anonymization, JS, API, SQL enrichments) | ✅ | ✅ (no UI or API) | +| [Data structures tooling and API](/docs/data-product-studio/data-structures/manage/index.md) | ✅ | ❌ | +| [Data products](/docs/data-product-studio/data-products/index.md) | ✅ | ❌ | | [Data modeling management tooling](/docs/modeling-your-data/running-data-models-via-snowplow-bdp/dbt/index.md) | ✅ | ❌ | | Jobs monitoring dashboard | ✅ | ❌ | | Failed events alerting | ✅ | ❌ | | Failed events recoveries | ✅ | ❌ | | QA pipeline | ✅ | do-it-yourself | -| Fine grained user permissions (ACLs) | ✅ | ❌ | +| Fine-grained user permissions using access control lists | ✅ | ❌ | | API key access | ✅ | ❌ | |

[Data Model Packs](/docs/modeling-your-data/visualization/index.md)

| BDP | [Community Edition](/docs/get-started/snowplow-community-edition/index.md) | | **Digital Analytics** | | | | Funnel builder | ✅ | ❌ | -| User & Marketing Analytics | ✅ | ❌ | +| User and Marketing Analytics | ✅ | ❌ | | Marketing Attribution | ✅ | ❌ | -| Video & Media | ✅ | ❌ | -| [Unified, Utils, Attribution, Media, Normalize data models](/docs/modeling-your-data/index.md) | ✅ | ❌ | +| Video and Media | ✅ | ❌ | +| [Unified Digital, Attribution, Media Player, Ecommerce, Normalize, Utils data models](/docs/modeling-your-data/index.md) | ✅ | ❌ | | **Ecommerce Analytics** | | | | Ecommerce Analytics | ✅ | ❌ | | [Ecommerce data model](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-ecommerce-data-model/index.md) | ✅ | ❌ | -|

Performance & Resilience

| BDP | [Community Edition](/docs/get-started/snowplow-community-edition/index.md) | +|

Extensions

| BDP | [Community Edition](/docs/get-started/snowplow-community-edition/index.md) | +| Reverse ETL, powered by Census | ✅ | ❌ | +| Audience Hub, powered by Census | ✅ | ❌ | +|

Performance and Resilience

| BDP | [Community Edition](/docs/get-started/snowplow-community-edition/index.md) | | Outage Protection | ✅ | ❌ | | Global Availability | ✅ | ❌ | -|

Infrastructure & Security

| BDP | [Community Edition](/docs/get-started/snowplow-community-edition/index.md) | +|

Infrastructure and Security

| BDP | [Community Edition](/docs/get-started/snowplow-community-edition/index.md) | | **High** | | | | HTTP access controls | ✅ | ❌ | | VPC peering | ✅ | ❌ | diff --git a/docs/get-started/tracking/cookies-and-ad-blockers/index.md b/docs/get-started/tracking/cookies-and-ad-blockers/index.md index 67378e4fc7..3307279d17 100644 --- a/docs/get-started/tracking/cookies-and-ad-blockers/index.md +++ b/docs/get-started/tracking/cookies-and-ad-blockers/index.md @@ -21,14 +21,14 @@ Although first-party cookies don't allow sharing user and session identifiers ac Using Snowplow, you can set up your collector to be on the same domain as the website, which is the requirement for the use of first-party cookies. To learn how to set up the collector domain, [visit this page](/docs/sources/first-party-tracking/index.md). -**Strategy 2: Snowplow ID service for Safari ITP** +**Strategy 2: Snowplow Cookie Extension service for Safari ITP** As of Safari 16.4 released in April 2023, Safari sets the [lifetime of server-set cookies](https://webkit.org/tracking-prevention/#cname-and-third-party-ip-address-cloaking-defense) to a maximum of 7 days under some circumstances even if they are first-party cookies. This greatly limits the effectiveness of tracking a customer journey where users are not regularly returning to your website. In particular, it affects the `network_userid` identifier in Snowplow events. -Snowplow provides the ID service solution that fully mitigates the impact of this change. -Visit the [documentation for the ID service](/docs/sources/trackers/javascript-trackers/web-tracker/browsers/index.md#itp-mitigation) to learn more. +Snowplow provides the Cookie Extension service solution that fully mitigates the impact of this change. +Visit the [documentation for the Cookie Extension service](/docs/events/cookie-extension/index.md) to learn more. ## 2. Mitigating the impact of ad-blockers diff --git a/docs/get-started/tracking/index.md b/docs/get-started/tracking/index.md index 458b212a3d..68a27a3e31 100644 --- a/docs/get-started/tracking/index.md +++ b/docs/get-started/tracking/index.md @@ -138,6 +138,6 @@ We have many different trackers in different programming languages, in case the :::tip -For quick testing, you might be tempted to send data to your Collector URL using a basic command-line tool like `cURL`. However, you would need to ensure that the data format follows our [tracker protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). Instead, take a look at the [command-line tracker](/docs/sources/trackers/snowplow-tracking-cli/index.md) that will do this for you. +For quick testing, you might be tempted to send data to your Collector URL using a basic command-line tool like `cURL`. However, you would need to ensure that the data format follows our [tracker protocol](/docs/events/index.md). Instead, take a look at the [command-line tracker](/docs/sources/trackers/snowplow-tracking-cli/index.md) that will do this for you. ::: diff --git a/docs/glossary/index.md b/docs/glossary/index.md new file mode 100644 index 0000000000..51691160f7 --- /dev/null +++ b/docs/glossary/index.md @@ -0,0 +1,80 @@ +--- +title: "Glossary" +date: "2025-05-12" +sidebar_position: 100 +--- + +This page provides a glossary of terms used by Snowplow. + +To help clarify, we've categorized the terms: +* Component: a pipeline application, package, SDK, or other code-based tool or set of tools, e.g. Snowplow Micro +* Concept: names for Snowplow things and ideas, e.g. data product +* Legal: about licensing, e.g. SLULA +* Offering: a Snowplow product that you can buy, e.g. Snowplow BDP Cloud + +| Term | Category | Description | More information | +| -------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| **Atomic events table** | Concept | Core warehouse table containing all Snowplow events | [Single table](/docs/fundamentals/canonical-event/index.md#single-table) | +| **Atomic fields** | Concept | Core event properties defined by the Snowplow atomic schema | [Out-of-the-box fields](/docs/fundamentals/canonical-event/index.md#out-of-the-box-fields) | +| **Audience Hub** | Offering | Customer segmentation in warehouse, powered by Census | | +| **Collection** | Concept | Generation of event data and sending to an event collector endpoint | [Sources](/docs/sources/index.md) | +| **Collector** | Component | Application that receives and saves raw events, and forwards them to Enrich | [Collector](/docs/pipeline/collector/index.md) | +| **Context** | Concept | Deprecated name for entity | [Entities](/docs/fundamentals/entities/index.md) | +| **Cookie Extension service** | Concept | Process for extending cookie lifespans | [Cookie Extension](/docs/events/cookie-extension/index.md) | +| **Data contract** | Concept | Event definitions; set of data products | [Data Product Studio](/docs/data-product-studio/index.md) | +| **Data model** | Component | dbt SQL package for processing events in the warehouse | [Modeling your data](/docs/modeling-your-data/index.md) | +| **Data pipeline** | Concept | Set of applications for collecting, processing, and storing events | [Fundamentals](/docs/fundamentals/index.md) | +| **Data product** | Concept | Set of event specifications, plus metadata | [Data products](/docs/data-product-studio/data-products/index.md) | +| **Data Product Studio** | Offering | Tracking and data contracts tooling | [Data Product Studio](/docs/data-product-studio/index.md) | +| **Data quality** | Concept | Tooling and reporting related to failed events and QA | [Data quality](/docs/data-product-studio/data-quality/index.md) | +| **Data structure** | Concept | Schema, plus metadata | [Data structures](/docs/data-product-studio/data-structures/index.md) | +| **Derived events table** | Concept | Warehouse table of events generated by a data model | [Modeling your data with dbt](/docs/modeling-your-data/modeling-your-data-with-dbt/index.md) | +| **Destination** | Concept | Third-party data store or data activation platform that can receive Snowplow event data | [Destinations](/docs/fundamentals/destinations/index.md) | +| **Enrich** | Component | Application that validates and enriches events | [Enrichments](/docs/pipeline/enrichments/index.md) | +| **Enrichment** | Component | A process, run by Enrich, that adds to or modifies event data | [Enrichments](/docs/pipeline/enrichments/index.md) | +| **Entity** | Concept | Supplemental or additional data included in an event; a schema or data structure describing additional data | [Entities](/docs/fundamentals/entities/index.md) | +| **Event** | Concept | A payload, processed by a data pipeline, describing something that happened; the "main" schema or data structure (i.e. not an entity) in an event | [Events](/docs/fundamentals/events/index.md) | +| **Event specification** | Concept | Set of data structures, including event and entities, that an event payload should match | [Event specifications](/docs/data-product-studio/event-specifications/index.md) | +| **Event, canonical** | Concept | One of the original Snowplow events - page view, page ping, or the legacy ecommerce transaction events - that has contains data for some atomic fields, but no schema | [Canonical events](/docs/fundamentals/canonical-event/index.md) | +| **Event, enriched** | Concept | An event payload that's valid and has been successfully enriched | [Enrichments](/docs/pipeline/enrichments/index.md) | +| **Event, failed** | Concept | An event payload that the pipeline had some problem processing | [Failed events](/docs/fundamentals/failed-events/index.md) | +| **Event, self-describing** | Concept | Custom event, based on a custom schema | [Self-describing events](/docs/fundamentals/events/index.md#self-describing-events) | +| **Event, structured** | Concept | Legacy, proto-custom event | [Structured events](/docs/fundamentals/events/index.md#structured-events) | +| **Event, unstructured** | Concept | Deprecated name for self-describing event | [Self-describing events](/docs/fundamentals/events/index.md#self-describing-events) | +| **Event, valid** | Concept | An event payload that matches its schema definitions; an event that the pipeline has collected, validated, and enriched without failure (i.e. not a failed event) | [Failed events](/docs/fundamentals/failed-events/index.md) | +| **Extension** | Offering | Third-party integration | | +| **ID service** | Concept | Deprecated name for Cookie Extension service | [Cookie Extension](/docs/events/cookie-extension/index.md) | +| **Iglu** | Component | Schema registry and associated tooling | [Iglu](/docs/api-reference/iglu/index.md) | +| **License, Community** | Legal | Deprecated license for certain Snowplow components; SCL | [Copyright licenses](/docs/resources/copyright-license/index.md) | +| **License, Limited Use** | Legal | Non-production use license for certain Snowplow components; SLULA | [Copyright licenses](/docs/resources/copyright-license/index.md) | +| **License, Personal and Academic** | Legal | Personal and academic license for certain Snowplow components; SPAL | [Copyright licenses](/docs/resources/copyright-license/index.md) | +| **Loader** | Component | Application that loads data into warehouse or lake storage | [Warehouses and lakes](/docs/destinations/warehouses-lakes/index.md) | +| **Organization** | Concept | Your organization, in the context of account management and SSO | [Account management](/docs/account-management/index.md) | +| **Out-of-the-box** | Concept | Non-custom events, data products, schemas, etc. that are included with Snowplow | | +| **Registry** | Concept | Server that stores schemas (schema repository) | [Iglu repositories](/docs/api-reference/iglu/iglu-repositories/index.md) | +| **Reverse ETL** | Offering | Sync insights from warehouse to other tools, powered by Census | [Reverse ETL](/docs/destinations/reverse-etl/index.md) | +| **Schema** | Concept | JSON Schema that describes how data should look | [Schemas](/docs/fundamentals/schemas/index.md) | +| **Schema respository** | Concept | Server that stores schemas (schema registry) | [Iglu repositories](/docs/api-reference/iglu/iglu-repositories/index.md) | +| **SLULA** | Legal | Snowplow Limited Use License Agreement, a non-production use license | [Copyright licenses](/docs/resources/copyright-license/index.md) | +| **Snowbridge** | Component | Application that sends data streams into external destinations | [Snowbridge](/docs/destinations/forwarding-events/snowbridge/index.md) | +| **Snowplow BDP** | Offering | Full Snowplow product offering | [Snowplow BDP](/docs/get-started/snowplow-bdp/index.md) | +| **Snowplow BDP Cloud** | Offering | Snowplow running in a cloud hosted by Snowplow | [Snowplow BDP](/docs/get-started/snowplow-bdp/index.md) | +| **Snowplow BDP Console** | Offering | Web UI for Snowplow data management | | +| **Snowplow BDP Enterprise** | Offering | Deprecated name for Snowplow BDP Private Managed Cloud | [Snowplow BDP](/docs/get-started/snowplow-bdp/index.md) | +| **Snowplow BDP Private Managed Cloud** | Offering | Snowplow running in your own cloud | [Snowplow BDP](/docs/get-started/snowplow-bdp/index.md) | +| **Snowplow CLI** | Component | Tool for command-line management of data products and data structures | [Snowplow CLI](/docs/data-product-studio/snowplow-cli/index.md) | +| **Snowplow Community Edition** | Offering | Limited license (SLULA) Snowplow product offering | [Snowplow Community Edition](/docs/get-started/snowplow-community-edition/index.md) | +| **Snowplow Inspector** | Component | Browser extension for testing and validation of web tracking | [Snowplow Inspector](/docs/data-product-studio/data-quality/snowplow-inspector/index.md) | +| **Snowplow Micro** | Component | Testing and QA pipeline | [Snowplow Micro](/docs/data-product-studio/data-quality/snowplow-micro/index.md) | +| **Snowplow Mini** | Component | Sandbox development pipeline | [Snowplow Mini](/docs/api-reference/snowplow-mini/index.md) | +| **Snowtype** | Component | Tool for custom tracking code generation | [Snowtype](/docs/data-product-studio/snowtype/index.md) | +| **Snowtype CLI** | Component | Tool for command-line management of Snowtype code generation | [Snowtype CLI](/docs/data-product-studio/snowtype/using-the-cli/index.md) | +| **Source** | Concept | Tracker SDK or webhook that sends events to a collector endpoint | [Sources](/docs/sources/index.md) | +| **Source application** | Concept | Your application where you have implemented tracking | [Source applications](/docs/data-product-studio/source-applications/index.md) | +| **Tracker** | Component | SDK that sends events to an event collector endpoint | [Trackers](/docs/sources/trackers/index.md) | +| **Tracking catalog** | Concept | List of received event types in Snowplow BDP Console | +| TSV | Concept | Tab-separated values format, used for events within a Snowplow pipeline | [Enriched TSV format](/docs/fundamentals/canonical-event/understanding-the-enriched-tsv-format/index.md#overview---tsv-format) | +| **Validation** | Concept | Pipeline process of checking events against their schemas | | +| **Visualization** | Offering | Accompanying dashboard for a data model | [Visualizations](/docs/modeling-your-data/visualization/index.md) | +| **Webhook** | Component | API that allows you to send external data to Snowplow pipelines, usually third-party | [Webhooks](/docs/sources/webhooks/index.md) | +| **Workspace** | Concept | Isolated environment containing one production pipeline, and potentially multiple QA or development pipelines | | diff --git a/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-attribution-data-model/index.md b/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-attribution-data-model/index.md index 2be05418c6..d1f1ce689e 100644 --- a/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-attribution-data-model/index.md +++ b/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-attribution-data-model/index.md @@ -213,7 +213,7 @@ You can do either for campaigns, too, with the `snowplow__channels_to_exclude` a In order to reduce unneccesarily long paths you can apply a number of path transformations that are created as part of user defined functions automatically in your warehouse by the package. -In order to apply these transformations, all you have to do is to define them in the `snowplow__path_transforms` variable as a list of dictionaries, with the transformation name as key and optionally the parameter as value (for `remove_if_last_and_not_all` and `remove_if_not_all`). If the transformation requires no parameter you can just use `null` as values for the dictionary. For more details on how to do this, check out the [configuration page](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-configuration/attribution/index.mdx) E.g.: `{'exposure_path': null, 'remove_if_last_and_not_all': 'direct'}` +In order to apply these transformations, all you have to do is to define them in the `snowplow__path_transforms` variable as a dictionary. In case of `remove_if_last_and_not_all` and `remove_if_not_all` transformations, the transformation name is the key and a non-empty array is the value. For other transformations (`exposure_path`, `first_path`, `unique_path`), no additional parameter is required, you can just use `null` as values. For more details on how to do this, check out the [configuration page](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-configuration/attribution/index.mdx) E.g.: `{'exposure_path': null, 'remove_if_last_and_not_all': ['channel_to_remove_1', 'campaign_to_remove_1', 'campaign_to_remove_2']}` Please note that the transformations are applied on both campaign and channel paths equally.
Path transform options diff --git a/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-unified-data-model/index.md b/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-unified-data-model/index.md index 0012f0388c..4b0f9cd01b 100644 --- a/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-unified-data-model/index.md +++ b/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-unified-data-model/index.md @@ -48,16 +48,16 @@ While using any entity in our packages is possible thanks to [modeling entities] | Entity | Type | Enabled via Variable | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------------------------------------- | -| [YAUAA](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/device-and-browser/index.md#yauaa-context-for-user-agent-parsing) | web | snowplow__enable_yauaa | -| [IAB](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/device-and-browser/index.md#iab-context-for-spiders-and-robots) | web | snowplow__enable_iab | +| [YAUAA](/docs/events/ootb-data/device-and-browser/index.md#yauaa-context-for-user-agent-parsing) | web | snowplow__enable_yauaa | +| [IAB](/docs/events/ootb-data/device-and-browser/index.md#iab-context-for-spiders-and-robots) | web | snowplow__enable_iab | | [UA](/docs/pipeline/enrichments/available-enrichments/ua-parser-enrichment/index.md) | web | snowplow__enable_ua | -| [Browser](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/device-and-browser/index.md#browser-context) | web | snowplow\__enable_browser_context, snowplow\__enable_browser_context_2 (depending on schema versions tracked, when both are enabled the values are coalesced) | -| [Mobile](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/device-and-browser/index.md#mobile-context) | mobile | snowplow__enable_mobile_context | -| [Geolocation](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/geolocation/index.md#geolocation-context-entity-tracked-in-apps) | mobile | snowplow__enable_geolocation_context | -| [Application](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/app-information/index.md#application-context-entity-on-mobile-apps) | mobile | snowplow__enable_application_context | -| [Screen](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-and-screen-view-events/index.md#screen-view-events) | mobile | snowplow__enable_screen_context | -| [Deep Links](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/links-and-referrers/index.md#context-entity-attached-to-screen-view-events) | mobile | snowplow__enable_deep_link_context | -| [Screen Summary](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md#screen-summary-entity) | mobile | snowplow__enable_screen_summary_context | +| [Browser](/docs/events/ootb-data/device-and-browser/index.md#browser-context) | web | snowplow\__enable_browser_context, snowplow\__enable_browser_context_2 (depending on schema versions tracked, when both are enabled the values are coalesced) | +| [Mobile](/docs/events/ootb-data/device-and-browser/index.md#mobile-context) | mobile | snowplow__enable_mobile_context | +| [Geolocation](/docs/events/ootb-data/geolocation/index.md#geolocation-context-entity-tracked-in-apps) | mobile | snowplow__enable_geolocation_context | +| [Application](/docs/events/ootb-data/app-information/index.md#application-context-entity-on-mobile-apps) | mobile | snowplow__enable_application_context | +| [Screen](/docs/events/ootb-data/page-and-screen-view-events/index.md#screen-view-events) | mobile | snowplow__enable_screen_context | +| [Deep Links](/docs/events/ootb-data/links-and-referrers/index.md#context-entity-attached-to-screen-view-events) | mobile | snowplow__enable_deep_link_context | +| [Screen Summary](/docs/events/ootb-data/page-activity-tracking/index.md#screen-summary-entity) | mobile | snowplow__enable_screen_summary_context | ### Optional Modules | Module | Docs | Enabled via Variable | diff --git a/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-operation/debugging/index.md b/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-operation/debugging/index.md index 04048f42b0..c88f3b662e 100644 --- a/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-operation/debugging/index.md +++ b/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-operation/debugging/index.md @@ -32,7 +32,7 @@ The most common scenario that may happen is there are certain session_identifier We process the data based on sessions: for each run we take a look at the new events (with default 6 hours of lookback window) then look at the sessions manifest table and identify how far to look back in time to cover those sessions with new events as a whole. One overlooked common scenario is that in case of pipeline issues, if some data is getting processed by the model, but the rest are only added to the warehouse outside of that default 6 hour lookback window, then the package will leave those events behind unless the same session will have new events coming in, and it needs to be reprocessed as a whole again (unless the data modeling jobs were immediately paused after the pipeline went partially down). In such cases you need partial backfilling (see the [late loaded events](/docs/modeling-your-data/modeling-your-data-with-dbt/package-mechanics/late-arriving-data/index.md#late-loaded-events) section). -The events can also be [late sent](/docs/modeling-your-data/modeling-your-data-with-dbt/package-mechanics/late-arriving-data/#late-sent-events), in which case if they fall out of the limit, they will not get processed. +The events can also be [late sent](/docs/modeling-your-data/modeling-your-data-with-dbt/package-mechanics/late-arriving-data/index.md#late-sent-events), in which case if they fall out of the limit, they will not get processed. We also "quarantine" the sessions at times, as however hard we may try to filter out bots, there could be odd outliers that keep sessions alive for days, for which we have the `snowplow__max_session_days` variable. If bots keep sending events for longer than defined in that variable, the package will only process the first of those in a subsequent run and archives the session_identifier in the [quarantine table](/docs/modeling-your-data/modeling-your-data-with-dbt/package-mechanics/manifest-tables/index.md#quarantine-table) after it runs. In such a case it is always best to look for the missing event's session_identifier (domain_userid as defaulted for web events) in the table to explain why the event is missing. diff --git a/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-quickstart/normalize/index.md b/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-quickstart/normalize/index.md index 97cb622343..d461fc611b 100644 --- a/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-quickstart/normalize/index.md +++ b/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-quickstart/normalize/index.md @@ -126,7 +126,7 @@ vars: The purpose of this variable is to adjust the partitioning of the derived tables to use a different timestamp (e.g., derived_tstamp) that is more suitable for analytics in the next layer. :::warning Important Note on Custom Partition Timestamps -If you change `snowplow__partition_tstamp` to a different column (e.g., "loader_tstamp"), you MUST ensure that this column is included in the `event_columns` list in your normalize configuration for each event. Failing to do so will cause the models to fail, as the partition column must be present in the normalized output. +If you change `snowplow__partition_tstamp` to a different column (e.g., `load_tstamp`), you MUST ensure that this column is included in the `event_columns` list in your normalize configuration for each event. Failing to do so will cause the models to fail, as the partition column must be present in the normalized output. Example configuration when using a custom partition timestamp: ```json @@ -136,7 +136,7 @@ Example configuration when using a custom partition timestamp: "event_names": ["page_view"], "event_columns": [ "domain_userid", - "loader_tstamp", // Must include your custom partition timestamp here + "load_tstamp", // Must include your custom partition timestamp here "app_id" ], // ... rest of configuration diff --git a/docs/modeling-your-data/modeling-your-data-with-dbt/migration-guides/attribution/index.md b/docs/modeling-your-data/modeling-your-data-with-dbt/migration-guides/attribution/index.md new file mode 100644 index 0000000000..57bfa8f755 --- /dev/null +++ b/docs/modeling-your-data/modeling-your-data-with-dbt/migration-guides/attribution/index.md @@ -0,0 +1,13 @@ +--- +title: "Attribution" +sidebar_position: 20 +--- + +### Upgrading to 0.5.0 +- From now on the `snowplow__path_transforms` variable parameters only accept non-empty arrays for `remove_if_last_and_not_all` and `remove_if_not_all` variables instead of strings, please your variable overwrites in your dbt_project.yml accordingly. Previously you could only remove one specific channel or campaign, now you can do multiple, if needed. + +```yml title="dbt_project.yml" +vars: + snowplow_attribution: + snowplow__path_transforms: {'exposure_path': null, 'remove_if_last_and_not_all': ['channel_to_remove_1', 'campaign_to_remove_1, 'campaign_to_remove_2']} + ``` diff --git a/docs/modeling-your-data/modeling-your-data-with-dbt/migration-guides/web_to_unified/index.md b/docs/modeling-your-data/modeling-your-data-with-dbt/migration-guides/web_to_unified/index.md index 833b3e7815..588804fc2a 100644 --- a/docs/modeling-your-data/modeling-your-data-with-dbt/migration-guides/web_to_unified/index.md +++ b/docs/modeling-your-data/modeling-your-data-with-dbt/migration-guides/web_to_unified/index.md @@ -1,5 +1,5 @@ --- -title: "Web to Unified" +title: "Web to Unified Digital" sidebar_position: 1000 --- ```mdx-code-block @@ -8,9 +8,9 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; ``` -This migration guide is for the [Snowplow Web](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/legacy/dbt-web-data-model/index.md) (legacy dbt package) users who would like to upgrade to the [Snowplow Unified Digital](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-unified-data-model/index.md) package which is our most supported and feature-rich dbt package you can use to model web and/or mobile event data. +Follow this migration guide to upgrade from the legacy [Snowplow Web](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/legacy/dbt-web-data-model/index.md) dbt package to the [Snowplow Unified Digital](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-unified-data-model/index.md) package. Unified Digital is the most supported and feature-rich Snowplow dbt package, which you can use to model web and/or mobile event data. -### Simplified Upgrade Overview +## Simplified upgrade overview

-### Breaking changes between the packages +## Breaking changes between the packages -- the `page_views` table has been renamed to `views` -- the `domain_userid` field has been renamed to `user_identifier`, as you now have the ability to define your own custom logic / alternative user id field for the aggregation -- the `domain_sessionid` has been renamed to `session_identifier`, as you now have the ability to define your own custom logic / alternative session id field for the aggregation -- apart from these, fields generated by the the out-of-the-box entities and enrichments have been added a prefix to indicate where they are coming from e.g. `device_version` has been renamed to `yauaa__device_version` -- these out-of-the-box entities and enrichments can optionally be enabled or disabled for the model (previously these values were there as NULLs) through variables e.g. `snowplow__enable_yauaa: true` which are then flattened automatically within the `base_events_this_run` table and can be referred to from there directly for custom models, if needed -- some package variables have been renamed (as well as new ones added) +- The `page_views` table has been renamed to `views` +- The `domain_userid` field has been renamed to `user_identifier`, as you now have the ability to define your own custom logic / alternative user id field for the aggregation +- The `domain_sessionid` has been renamed to `session_identifier`, as you now have the ability to define your own custom logic / alternative session id field for the aggregation +- Apart from these, fields generated by the out-of-the-box entities and enrichments have been added a prefix to indicate where they are coming from, e.g. `device_version` has been renamed to `yauaa__device_version` +- These out-of-the-box entities and enrichments can be optionally enabled or disabled for the model (previously these values were there as NULLs) through variables e.g. `snowplow__enable_yauaa: true` which are then flattened automatically within the `base_events_this_run` table and can be referred to from there directly for custom models, if needed +- Some package variables have been renamed, as well as new ones added -### Things to bear in mind (no 100% accuracy!) +## Things to bear in mind -Due to the above mentioned breaking changes, ideally it is best to start from scratch and run the new package on your whole historic events dataset. However, in certain scenarios (e.g. in case of large data volumes) to save time, effort and cost it may be useful to try and upgrade instead using the existing modeled derived dataset. +Due to the breaking changes, ideally it's best to start from scratch and run the new package on your whole historic events dataset. This could be costly in both time and effort. In certain scenarios, e.g. in case of large data volumes, it may be useful to try and upgrade instead using the existing modeled derived dataset. -Please bear in mind that the there is no 100% accurate upgrade solution but with the below steps and sql scripts we may be able to get you to roughly 95% of the way there: +There is no 100% accurate upgrade solution, but with this guide you may be able to get 95% of the way there. -1. Incomplete / inaccurate fields for historic data: -The unified package contains a list of new fields, some of which we can compute on a row-by-row basis, in which case we provided update scripts to compute them for your existing derived data. There are, however, a few other new fields that are a result of aggregate or other computation that we cannot calculate without a full refresh. E.g. `absolute_time_in_s` for users therefore they will stay NULL. Then when a new event comes to update that record it may either correct it or it will just be inaccurate. +1. **Incomplete or inaccurate fields for historic data**: the unified package contains a list of new fields, some of which we can compute on a row-by-row basis, in which case we provided update scripts to compute them for your existing derived data. There are, however, a few other new fields that are a result of aggregate or other computation that we cannot calculate without a full refresh. E.g. `absolute_time_in_s` for users therefore they will stay `NULL`. Then when a new event comes to update that record it may either correct it or it will just be inaccurate. -2. Fields that are not available in the out-of-the-box derived tables: -There are a few fields that we have dropped as they were incorporated into a new field based on different grouping. There may also be custom fields you have added to the derived tables. The below passthrough variables come in handy in this case: +2. **Fields that aren't available in the out-of-the-box derived tables**: there are a few fields that we've dropped as they were incorporated into a new field based on different grouping. There may also be custom fields you have added to the derived tables. The below passthrough variables come in handy in this case: ```yml snowplow__view_passthroughs: [] snowplow__session_passthroughs: [] @@ -62,18 +60,20 @@ There are a few fields that we have dropped as they were incorporated into a new For more on this, have a look at the [passthrough fields](/docs/modeling-your-data/modeling-your-data-with-dbt/package-features/passthrough-fields/index.md) section. -### Upgrade steps +## Upgrade steps -#### Step 1: Migrate to the latest version of the web package +### Step 1: Migrate to the latest version of the Web package -Once you decided you would like to go ahead with the upgrade process you will first need to make sure your version of the web model is on par with the latest ( v.1.0.1). The [Web model migration guides](/docs/modeling-your-data/modeling-your-data-with-dbt/migration-guides/web/index.md) will help you decide what other changes you need to take into consideration and if the changes apply to your warehouse, you may need to execute the upgrade sql scripts to bridge the gap. +Once you decided you would like to go ahead with the upgrade process you will first need to make sure your version of the web model is version 1.0.0 or version 1.0.1. The [Web model migration guides](/docs/modeling-your-data/modeling-your-data-with-dbt/migration-guides/web/index.md) will help you decide what other changes you need to take into consideration. If the changes apply to your warehouse, you may need to execute the upgrade SQL scripts to bridge the gap. -#### Step 2: Execute SQL scripts to create the new tables +### Step 2: Execute SQL scripts to create the new tables -You will then need to execute a list of sql scripts we provide below, which will first create the new tables based on your existing derived tables created by the web package, then make the changes (e.g. renaming, adding, dropping and updating columns wherever possible). The manifest tables will also be altered making sure that you will then have everything ready for a new run in the unified package as if nothing happened. +The provided SQL scripts will first create the new tables based on your existing derived tables created by the web package. Secondly, they will make the changes i.e. renaming, adding, dropping, and updating columns wherever possible, including in the manifest tables. You will then have everything ready for a new run in the Unified Digital package as if nothing happened. -Execute the below sql scripts with your database IDE to create your new derived and manifest tables at once without having to reprocess your event data from scratch. Make sure to update `(your_schema)_derived` to match your derived schema name beforehand. Please also be aware you might need to adjust the data `varchar` data type to `string` depending on your warehouse (Bigquery, Databricks users mainly) or limit it to the maximum in case there are limitations (potentially Redshift). +Update `(your_schema)` in the SQL scripts to match your derived schema name. Execute the scripts with your database IDE to create your new derived and manifest tables without having to reprocess your event data from scratch. + +You might need to adjust the data `varchar` data type to `string` depending on your warehouse (most likely to be relevant for BigQuery or Databricks users) or limit it to the maximum in case there are limitations (potentially Redshift).

@@ -83,7 +83,7 @@ Execute the below sql scripts with your database IDE to create your new derived create table (your_schema)_derived.snowplow_unified_views as (select * from (your_schema)_derived.snowplow_web_page_views); create table (your_schema)_derived.snowplow_unified_sessions as (select * from (your_schema)_derived.snowplow_web_sessions); create table (your_schema)_derived.snowplow_unified_users as (select * from (your_schema)_derived.snowplow_web_users); -create table (your_schema)_derived.snowplow_unified_incremental_manifest as (select * from (your_schema)_derived.snowplow_web_incremental_manifest); +create table (your_schema)_snowplow_manifest.snowplow_unified_incremental_manifest as (select * from (your_schema)_snowplow_manifest.snowplow_web_incremental_manifest); create table (your_schema)_snowplow_manifest.snowplow_unified_base_sessions_lifecycle_manifest as (select * from (your_schema)_snowplow_manifest.snowplow_web_base_sessions_lifecycle_manifest) alter table (your_schema)_derived.snowplow_unified_views rename column domain_sessionid to session_identifier; @@ -241,9 +241,9 @@ where 1=1; ```
-#### Step 3: Setting up a new dbt project for unified +### Step 3: Setting up a new dbt project for Unified Digital -Due to a package conflict resulting from the last web and latest unified requiring a different version of the snowplow-utils package it is probably best to create a new dbt project for running the package. +Due to a package conflict resulting from the last Web and Unified Digital releases requiring a different version of the `snowplow-utils` package, it's probably best to create a new dbt project for running the package. **3.1 Packages.yml** @@ -255,7 +255,7 @@ packages: **3.2 Project.yml** -In the project.yml file make sure to disable the mobile events: +In the project.yml file, disable the mobile events: ```yml vars: @@ -263,7 +263,7 @@ vars: snowplow__enable_mobile: false ``` -In case you changed any of the default variables in your web project, add them here as well. Bear in mind that while 90% of the variables stayed the same, there are some notable changes, deletions, additions and default modifications, please have a look below or at the detailed [configuration](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-configuration/index.md) page and adjust accordingly: +If you changed any of the default variables in your web project, add them here as well. While 90% of the variables stayed the same, there are some notable changes, deletions, additions, and default modifications. Have a look below or at the detailed [configuration](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-configuration/index.md) page and adjust accordingly: **Removed variables:** - `snowplow__limit_page_views_to_session` @@ -296,14 +296,14 @@ In case you changed any of the default variables in your web project, add them h - `snowplow__session_identifiers`: `[{"schema" : "atomic", "field" : "domain_sessionid"}]` - `snowplow__user_identifiers`: `[{"schema": "atomic", "field" : "domain_userid"}]` to none -`snowplow__databricks_catalog`: 'hive_metastore' +- `snowplow__databricks_catalog`: `hive_metastore` -#### Step 4: Verifying the new derived datasets +### Step 4: Verifying the new derived datasets -At this stage you could potentially run both packages simultaneously until you make sure you are happy to stop the old jobs that updated the web package. +At this stage you could potentially run both packages simultaneously until you are happy to stop the old jobs that updated the Web package. -We have also provided views which replicate the original derived tables to help you maintain your existing reporting (in case you use the original derived tables as a source for your BI tool or for downstream data models). +If you used the original derived tables as a source for your BI tool or for downstream data models, you can use the views below to replicate the original tables. This can help you maintain your existing reporting.
SQL scripts to create views diff --git a/docs/modeling-your-data/modeling-your-data-with-dbt/package-features/identity-stitching/index.md b/docs/modeling-your-data/modeling-your-data-with-dbt/package-features/identity-stitching/index.md index 095d8e1eb6..bbbb83b916 100644 --- a/docs/modeling-your-data/modeling-your-data-with-dbt/package-features/identity-stitching/index.md +++ b/docs/modeling-your-data/modeling-your-data-with-dbt/package-features/identity-stitching/index.md @@ -25,7 +25,7 @@ This works by having an `User Mapping` table that collects and incrementally upd The `snowplow_unified` package means that all the user data, from both web and mobile, is modeled in one place. This makes it easy to effectively perform cross-platform stitching, which means that as soon as a users identify themselves by logging in as the same user on separate platforms, all the user data will be found within one package making it convenient for performing further analysis. We encourage everyone to take the base stitching logic provided by the package further by applying a custom aggregation downstream layer that takes the first/last fields per stitched_user_id from the users table as well a applying additional stitching based on custom user_mapping table(s) depending on need. :::info Multiple user_id / user identifier -In order for the user_mapping table to successfully update the stitched_user_id field in the users table, it needs to stay unique on session_identifier which means that if for some reason there are multiple user_ids per user_identifier, we take the latest one. For a standard use case when the user_identifier is a cookie based domain_userid and the user_stitching_id is the logged in atomic.user_id field, we encourage everyone to [remove cookies](/docs/sources/trackers/javascript-trackers/web-tracker/anonymous-tracking/index.md#clear-user-data) to force creating a new session upon the user log out action to avoid a scenario when multiple users log in and out quickly after one another on the same device (e.g. school, library). For tracking advice, have a look at [this](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/user-and-session-identification/index.md#reset-generated-identifiers-after-the-user-logs-out/) documentation. +In order for the user_mapping table to successfully update the stitched_user_id field in the users table, it needs to stay unique on session_identifier which means that if for some reason there are multiple user_ids per user_identifier, we take the latest one. For a standard use case when the user_identifier is a cookie based domain_userid and the user_stitching_id is the logged in atomic.user_id field, we encourage everyone to [remove cookies](/docs/sources/trackers/javascript-trackers/web-tracker/anonymous-tracking/index.md#clear-user-data) to force creating a new session upon the user log out action to avoid a scenario when multiple users log in and out quickly after one another on the same device (e.g. school, library). For tracking advice, have a look at [this](/docs/events/ootb-data/user-and-session-identification/index.md#reset-generated-identifiers-after-the-user-logs-out/) documentation. ::: diff --git a/docs/modeling-your-data/running-data-models-via-snowplow-bdp/dbt/images/data-models-navbar.png b/docs/modeling-your-data/running-data-models-via-snowplow-bdp/dbt/images/data-models-navbar.png new file mode 100644 index 0000000000..da164f86cf Binary files /dev/null and b/docs/modeling-your-data/running-data-models-via-snowplow-bdp/dbt/images/data-models-navbar.png differ diff --git a/docs/modeling-your-data/running-data-models-via-snowplow-bdp/dbt/index.md b/docs/modeling-your-data/running-data-models-via-snowplow-bdp/dbt/index.md index 8394673fbb..684d018e16 100644 --- a/docs/modeling-your-data/running-data-models-via-snowplow-bdp/dbt/index.md +++ b/docs/modeling-your-data/running-data-models-via-snowplow-bdp/dbt/index.md @@ -173,9 +173,9 @@ import DbtPrivs from "@site/docs/reusable/dbt-privs/_index.md" ### 2. The data modeling configuration -Data models can be configured via the Snowplow BDP Console: +Data models can be configured via the [Data Models](https://console.snowplowanalytics.com/data-models) page in Snowplow BDP Console: -![](images/Screenshot-2021-11-15-at-20.15.28.png) +![](images/data-models-navbar.png) In the first step, you can provide the data model name, a description, and the owner(s) of the data model that will be alerted in case of failure. Finally select the engine and version that should run your datamodel (dbt in this case): diff --git a/docs/modeling-your-data/running-data-models-via-snowplow-bdp/images/data-models.png b/docs/modeling-your-data/running-data-models-via-snowplow-bdp/images/data-models.png index 69065157b6..a1c352f5e1 100644 Binary files a/docs/modeling-your-data/running-data-models-via-snowplow-bdp/images/data-models.png and b/docs/modeling-your-data/running-data-models-via-snowplow-bdp/images/data-models.png differ diff --git a/docs/modeling-your-data/running-data-models-via-snowplow-bdp/images/warehouse-connections.png b/docs/modeling-your-data/running-data-models-via-snowplow-bdp/images/warehouse-connections.png index c75de6a1f0..edee87cdc3 100644 Binary files a/docs/modeling-your-data/running-data-models-via-snowplow-bdp/images/warehouse-connections.png and b/docs/modeling-your-data/running-data-models-via-snowplow-bdp/images/warehouse-connections.png differ diff --git a/docs/modeling-your-data/running-data-models-via-snowplow-bdp/index.md b/docs/modeling-your-data/running-data-models-via-snowplow-bdp/index.md index d17ed50a06..904a42da48 100644 --- a/docs/modeling-your-data/running-data-models-via-snowplow-bdp/index.md +++ b/docs/modeling-your-data/running-data-models-via-snowplow-bdp/index.md @@ -20,7 +20,7 @@ import TabItem from '@theme/TabItem'; You can also create [custom data models](/docs/modeling-your-data/running-data-models-via-snowplow-bdp/dbt/index.md). ## Create a warehouse connection -Begin by creating a new warehouse connection. It will be used by a data model to connect to your warehouse. Click on the "Set up new connection" button on the [Data Models page](https://console.snowplowanalytics.com/data-models) and fill in all the necessary details. +Begin by creating a new warehouse connection. It will be used by a data model to connect to your warehouse.Go to [Destinations/Connections](https://console.snowplowanalytics.com/connections), click on "Set up connection", and fill in all the necessary details. ![](./images/warehouse-connections.png) @@ -33,7 +33,7 @@ You might have already set up a warehouse connection for loading the data. Data Supported destinations are Snowflake, Databricks, Redshift and BigQuery. ## Create a data model -To create a new data model, click the "Add data model" button. Then, select the data model you're interested in, such as [Unified Digital](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-unified-data-model/index.md), and the warehouse connection it should use. You can also specify the owners of the data model who will be alerted in case of failure. +To create a new data model, click the "Add data model" button in the [Data Models](https://console.snowplowanalytics.com/data-models) page. Then, select the data model you're interested in, such as [Unified Digital](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-unified-data-model/index.md), and the warehouse connection it should use. You can also specify the owners of the data model who will be alerted in case of failure. ![](images/data-models.png) diff --git a/docs/pipeline/collector/images/image-1.png b/docs/pipeline/collector/images/image-1.png index ca690ffc87..5c6c629a46 100644 Binary files a/docs/pipeline/collector/images/image-1.png and b/docs/pipeline/collector/images/image-1.png differ diff --git a/docs/pipeline/collector/images/image-2.png b/docs/pipeline/collector/images/image-2.png index 4bb38d8604..6207510285 100644 Binary files a/docs/pipeline/collector/images/image-2.png and b/docs/pipeline/collector/images/image-2.png differ diff --git a/docs/pipeline/collector/index.md b/docs/pipeline/collector/index.md index a27913af77..298d5d2e11 100644 --- a/docs/pipeline/collector/index.md +++ b/docs/pipeline/collector/index.md @@ -12,13 +12,13 @@ Read more about the technical aspects of the collector [here](/docs/api-referenc The easiest way to access collector configuration is to view it within the Snowplow BDP Console. To do that, after you log in click on _Pipeline Configuration_ under the respective pipeline's navigation menu: -![This image has an empty alt attribute; its file name is image-1.png](images/image-1.png) +![](images/image-1.png) Selecting the pipeline configuration tab You can then view your configuration, with the default values displayed for empty fields: -![This image has an empty alt attribute; its file name is image-2.png](images/image-2.png) +![](images/image-2.png) Example collector configuration diff --git a/docs/pipeline/enrichments/available-enrichments/custom-javascript-enrichment/writing/index.md b/docs/pipeline/enrichments/available-enrichments/custom-javascript-enrichment/writing/index.md index 15a66ccf7d..7627491bcf 100644 --- a/docs/pipeline/enrichments/available-enrichments/custom-javascript-enrichment/writing/index.md +++ b/docs/pipeline/enrichments/available-enrichments/custom-javascript-enrichment/writing/index.md @@ -243,25 +243,12 @@ You might be tempted to update derived entities in a similar way by using `event ## Discarding the event -Sometimes you don’t want the event to appear in your data warehouse or lake, e.g. because you suspect it comes from a bot and not a real user. In this case, you can `throw` an exception in your JavaScript code, which will send the event to [failed events](/docs/fundamentals/failed-events/index.md): +```mdx-code-block +import DiscardingEvents from "@site/docs/reusable/discarding-events/_index.md" -```js -const botPattern = /.*Googlebot.*/; - -function process(event) { - const useragent = event.getUseragent(); - - if (useragent !== null && botPattern.test(useragent)) { - throw "Filtered event produced by Googlebot"; - } -} + ``` -:::caution - -This will create an “enrichment failure” failed event, which may be tricky to distinguish from genuine failures in your enrichment code, e.g. due to a mistake. In the future, we might provide a better mechanism for discarding events. - -::: ## Accessing Java methods diff --git a/docs/pipeline/enrichments/available-enrichments/pii-pseudonymization-enrichment/index.md b/docs/pipeline/enrichments/available-enrichments/pii-pseudonymization-enrichment/index.md index a06205d01d..4aa316f2a4 100644 --- a/docs/pipeline/enrichments/available-enrichments/pii-pseudonymization-enrichment/index.md +++ b/docs/pipeline/enrichments/available-enrichments/pii-pseudonymization-enrichment/index.md @@ -12,7 +12,7 @@ In Europe the obligations regarding Personal Data handling have been outlined on ## Configuration -- [Schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.enrichments/pii_enrichment_config/jsonschema/2-0-0) +- [Schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.enrichments/pii_enrichment_config/jsonschema/2-0-1) - [Example](https://github.com/snowplow/enrich/blob/master/config/enrichments/pii_enrichment_config.json) ```mdx-code-block @@ -23,7 +23,7 @@ import TestingWithMicro from "@site/docs/reusable/test-enrichment-with-micro/_in Two types of fields can be configured to be hashed: -- `pojo`: field that is effectively a scalar field in the enriched event (full list of fields that can be pseudonymized [here](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.enrichments/pii_enrichment_config/jsonschema/2-0-0#L43-L60)) +- `pojo`: field that is effectively a scalar field in the enriched event (full list of fields that can be pseudonymized [here](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.enrichments/pii_enrichment_config/jsonschema/2-0-1#L43-L60)) - `json`: field contained inside a self-describing JSON (e.g. in `unstruct_event`) With the configuration example, the fields `user_id` and `user_ipaddress` of the enriched event would be hashed, as well as the fields `email` and `ip_opt` of the unstructured event in case its schema matches _iglu:com.mailchimp/subscribe/jsonschema/1-\*-\*_. @@ -42,9 +42,16 @@ It's **important** to keep these things in mind when using this enrichment: - Hashing a field can change its format (e.g. email) and its length, thus making a whole valid original event invalid if its schema is not compatible with the hashing. - When updating the `salt` after it has already been used, same original values hashed with previous and new salt will have different hashes, thus making a join impossible and/or creating duplicate values. +### `anonymousOnly` mode +Enrich 5.3.0 introduced the `anonymousOnly` mode. When [anonymousOnly](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.enrichments/pii_enrichment_config/jsonschema/2-0-1#L155) is set to true, PII fields are masked only in events tracked in anonymous mode (i.e. the `SP-Anonymous` header is present). + +This is useful for compliance with regulation such as GDPR, where you would start with [anonymous tracking](/docs/sources/trackers/javascript-trackers/web-tracker/anonymous-tracking/index.md) by default (all identifiers are masked) and switch to non-anonymous tracking when the user consents to data collection (all identifiers are kept). + +By default, `anonymousOnly` is `false`, i.e. PII fields are always masked. + ## Input -[These fields](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.enrichments/pii_enrichment_config/jsonschema/2-0-0#L43-L60) of the enriched event and any field of an unstructured event or context can be hashed. +[These fields](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.enrichments/pii_enrichment_config/jsonschema/2-0-1#L43-L60) of the enriched event and any field of an unstructured event or context can be hashed. ## Output diff --git a/docs/pipeline/enrichments/available-enrichments/yauaa-enrichment/index.md b/docs/pipeline/enrichments/available-enrichments/yauaa-enrichment/index.md index 9b31f68177..bf98eafeb4 100644 --- a/docs/pipeline/enrichments/available-enrichments/yauaa-enrichment/index.md +++ b/docs/pipeline/enrichments/available-enrichments/yauaa-enrichment/index.md @@ -52,7 +52,7 @@ Only one parameter can be set in the configuration : `cacheSize`. This field det This enrichment uses the following inputs: -- The `useragent` field from the Snowplow event. Typically this field is taken from the `User-Agent` HTTP header. But Snowplow trackers can also override the user agent by setting the `ua` field [in the tracker payload](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +- The `useragent` field from the Snowplow event. Typically this field is taken from the `User-Agent` HTTP header. But Snowplow trackers can also override the user agent by setting the `ua` field [in the tracker payload](/docs/events/index.md). - Client hint HTTP headers. These are [a set of standard headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Client_hints) such as `Sec-CH-UA` which provide extra detail about the user agent. ## Output diff --git a/docs/pipeline/enrichments/filtering-bot-events/index.md b/docs/pipeline/enrichments/filtering-bot-events/index.md new file mode 100644 index 0000000000..9ea9c7beab --- /dev/null +++ b/docs/pipeline/enrichments/filtering-bot-events/index.md @@ -0,0 +1,10 @@ +--- +title: "Filtering bot events" +sidebar_position: 100 +--- + +```mdx-code-block +import DiscardingEvents from "@site/docs/reusable/discarding-events/_index.md" + + +``` \ No newline at end of file diff --git a/docs/pipeline/enrichments/index.md b/docs/pipeline/enrichments/index.md index 7d8523a91f..e0575ec927 100644 --- a/docs/pipeline/enrichments/index.md +++ b/docs/pipeline/enrichments/index.md @@ -65,7 +65,7 @@ Similarly, `page_referrer` gets the value from `refr`, which represents the r | `refr_urlquery` | Querystring | | `refr_urlfragment` | Fragment (anchor) | -Additionally the derived timestamp is calculated, `derived_tstamp`. See [this blog post](https://snowplowanalytics.com/blog/2015/09/15/improving-snowplows-understanding-of-time/) for more details. +Additionally the derived timestamp is calculated, `derived_tstamp`. See [Timestamps](/docs/events/timestamps/index.md) for more details. Finally, contexts, unstructured events and the relevant configurable enrichments (if enabled) are validated against their corresponding JSON schemas and the array of the derived contexts is assembled. diff --git a/docs/pipeline/enrichments/managing-enrichments/images/ViewEnrichments.gif b/docs/pipeline/enrichments/managing-enrichments/images/ViewEnrichments.gif deleted file mode 100644 index 75d1b3463f..0000000000 Binary files a/docs/pipeline/enrichments/managing-enrichments/images/ViewEnrichments.gif and /dev/null differ diff --git a/docs/pipeline/enrichments/managing-enrichments/images/ViewEnrichments.png b/docs/pipeline/enrichments/managing-enrichments/images/ViewEnrichments.png new file mode 100644 index 0000000000..f3498e817e Binary files /dev/null and b/docs/pipeline/enrichments/managing-enrichments/images/ViewEnrichments.png differ diff --git a/docs/pipeline/enrichments/managing-enrichments/images/configure-and-enable.png b/docs/pipeline/enrichments/managing-enrichments/images/configure-and-enable.png new file mode 100644 index 0000000000..f94e707c75 Binary files /dev/null and b/docs/pipeline/enrichments/managing-enrichments/images/configure-and-enable.png differ diff --git a/docs/pipeline/enrichments/managing-enrichments/images/deploy-enrichment-1.png b/docs/pipeline/enrichments/managing-enrichments/images/deploy-enrichment-1.png new file mode 100644 index 0000000000..6249134609 Binary files /dev/null and b/docs/pipeline/enrichments/managing-enrichments/images/deploy-enrichment-1.png differ diff --git a/docs/pipeline/enrichments/managing-enrichments/images/deploy-enrichment-2.png b/docs/pipeline/enrichments/managing-enrichments/images/deploy-enrichment-2.png new file mode 100644 index 0000000000..b4b67d6ead Binary files /dev/null and b/docs/pipeline/enrichments/managing-enrichments/images/deploy-enrichment-2.png differ diff --git a/docs/pipeline/enrichments/managing-enrichments/images/view-differences.png b/docs/pipeline/enrichments/managing-enrichments/images/view-differences.png new file mode 100644 index 0000000000..99618df3b4 Binary files /dev/null and b/docs/pipeline/enrichments/managing-enrichments/images/view-differences.png differ diff --git a/docs/pipeline/enrichments/managing-enrichments/index.md b/docs/pipeline/enrichments/managing-enrichments/index.md index 48ac4077d7..b8aa19ecc7 100644 --- a/docs/pipeline/enrichments/managing-enrichments/index.md +++ b/docs/pipeline/enrichments/managing-enrichments/index.md @@ -7,39 +7,40 @@ sidebar_custom_props: --- -Snowplow BDP Console enables you to manage the Enrichments that run on each of your environments. +Snowplow BDP Console enables you to manage the Enrichments that run on each of your pipelines. -To start managing Enrichments, navigate to the environment you'd like to manage and select _Enrichments_ in the environment menu. +To start managing Enrichments, navigate to the pipeline you'd like to manage and click on the _Enrichments_ tab. -## View which Enrichments are running for an environment +## View which Enrichments are running for a pipeline -When you select navigate to the Enrichments screen you'll see a listing of all Enrichments and see their current status & last edited date for the environment. +When you select navigate to the Enrichments screen you'll see a listing of all Enrichments and see their current status & last edited date for the pipeline. -![](images/ViewEnrichments.gif) +![](images/ViewEnrichments.png) ## Enable /editing an Enrichment -You can enable and edit enrichments on any environment, but we recommend the following workflow to test the configuration before deploying to a pipeline: +You can enable and edit enrichments on any pipeline, but we recommend the following workflow to test the configuration before deploying it: -- Navigate to a sandbox environment (Snowplow Mini) +- Navigate to a sandbox (Snowplow Mini) - Enable and configure the Enrichment as required - Send some events to your Snowplow Mini endpoint and validate the fields appear as expected in the event payload - Deploy the configuration to your pipeline(s) -### Enable the enrichment on a sandbox environment +### Enable the enrichment on a sandbox **Navigate to a Snowplow Mini** and locate the enrichment you wish to enable. In the listing select _Configure and enable / Edit configuration_ from the pop up menu, or click the **Configure and enable / Edit config** button when viewing the enrichment. +![](images/configure-and-enable.png) +![](images/view-differences.png) + **On the configuration screen**, edit the JSON configuration ([refer to each individual enrichments documentation for support](/docs/pipeline/enrichments/available-enrichments/index.md)) and click _Validate._ If your configuration is valid you will be given the option to _Publish_ the enrichment to the environment. If it is invalid you will be given validation errors to correct. **_Publish_ your configuration** to the environment and then test it by sending some events to the Mini endpoint. -![](images/EnableEnrichment.gif) - Once you are happy with your configuration, follow [Deploying a configuration across environments](#deploy) to deploy the configuration to a pipeline. * * * @@ -53,9 +54,10 @@ You will need to copy a configuration across environments when: **Navigate to the Snowplow Mini** that you want to deploy from, and locate the Enrichment you want to deploy to another environment. -**Click _Deploy_** in either the pop-up menu on the Listing screen, or the button in the View Enrichment screen. +**Click _Deploy_**: -![](images/DisableEnrichment.gif) +![](images/deploy-enrichment-1.png) +![](images/deploy-enrichment-2.png) In the dialog that appears, select which environments you wish to copy to and click _Deploy configuration._ diff --git a/docs/resources/recipes-tutorials/recipe-basic-tracking-design/index.md b/docs/resources/recipes-tutorials/recipe-basic-tracking-design/index.md index bdd215481a..ba0bf9e169 100644 --- a/docs/resources/recipes-tutorials/recipe-basic-tracking-design/index.md +++ b/docs/resources/recipes-tutorials/recipe-basic-tracking-design/index.md @@ -209,41 +209,41 @@ Create a new HTML page with this content: ```html -
+
Form Name -
- -
+
+ +
-
- -
+
+ +
-
- -
-
+
+ +
+
-
+
-
- -
+
+ +
diff --git a/docs/reusable/define-custom-event/_index.md b/docs/reusable/define-custom-event/_index.md index 5c470f9130..29c56c069e 100644 --- a/docs/reusable/define-custom-event/_index.md +++ b/docs/reusable/define-custom-event/_index.md @@ -1,3 +1,3 @@ -You may wish to track events which are not directly supported by Snowplow and which [structured event tracking](/docs/sources/trackers/snowplow-tracker-protocol/custom-events/structured-events/index.md) does not adequately capture. Your event may have more than the five fields offered by `Structured` events, or its fields may not fit into the category-action-label-property-value model. The solution is Snowplow’s self-describing events. Self-describing events are a [data structure based on JSON Schemas](/docs/fundamentals/schemas/index.md) and can have arbitrarily many fields. +You may wish to track events which are not directly supported by Snowplow and which [structured event tracking](/docs/events/custom-events/structured-events/index.md) does not adequately capture. Your event may have more than the five fields offered by `Structured` events, or its fields may not fit into the category-action-label-property-value model. The solution is Snowplow’s self-describing events. Self-describing events are a [data structure based on JSON Schemas](/docs/fundamentals/schemas/index.md) and can have arbitrarily many fields. To define your own custom event, you will need to [create a corresponding schema](/docs/data-product-studio/data-structures/manage/index.md). Snowplow uses the schema to validate that the JSON containing the event properties is well-formed. diff --git a/docs/reusable/discarding-events/_index.md b/docs/reusable/discarding-events/_index.md new file mode 100644 index 0000000000..b31854f831 --- /dev/null +++ b/docs/reusable/discarding-events/_index.md @@ -0,0 +1,43 @@ +Sometimes you don’t want the event to appear in your data warehouse or lake, e.g. because you suspect it comes from a bot and not a real user. + +Starting with Enrich 5.3.0, it is possible to drop an event by calling `event.drop()` in JavaScript enrichment code: + +```js +const botPattern = /.*Googlebot.*/; + +function process(event) { + const useragent = event.getUseragent(); + + if (useragent !== null && botPattern.test(useragent)) { + event.drop(); + } +} +``` + +This mechanism can be used to drop not only good events, but also invalid events. The dropped events will not be sent to any stream or destination, thus lowering the infrastructure costs. + +:::caution + +There is no way to recover dropped events therefore use it with caution. + +::: + +Another way to discard events is throwing an exception in your JavaScript code, which will send the event to [failed events](/docs/fundamentals/failed-events/index.md): + +```js +const botPattern = /.*Googlebot.*/; + +function process(event) { + const useragent = event.getUseragent(); + + if (useragent !== null && botPattern.test(useragent)) { + throw "Filtered event produced by Googlebot"; + } +} +``` + +:::caution + +This will create an “enrichment failure” failed event, which may be tricky to distinguish from genuine failures in your enrichment code, e.g. due to a mistake. + +::: diff --git a/docs/signals/attributes/index.md b/docs/signals/attributes/index.md new file mode 100644 index 0000000000..3416f29beb --- /dev/null +++ b/docs/signals/attributes/index.md @@ -0,0 +1,108 @@ +--- +title: "Defining Attributes" +sidebar_position: 20 +description: "Attributes." +sidebar_label: "Attributes" +--- + +Attributes are the building blocks of Snowplow Signals. They represent specific facts about user behavior and are calculated based on events in your Snowplow pipeline. This guide explains how to define an `Attribute`, and use `Criteria` to filter events for precise data aggregation. + +- **Number of page views in the last 7 Days:** counts how many pages a user has viewed within the past week. +- **Last product viewed:** identifies the most recent product a user interacted with. +- **Previous purchases:** provides a record of the user's past transactions. + + +### Basic Usage + +An `Attribute` can be defined to count the number of pageviews in a session through the Python SDK as follows: + +```python +from snowplow_signals import Attribute, Event + +page_views_attribute = Attribute( + name='page_views_count', + type='int32', + events=[ + Event( + vendor="com.snowplowanalytics.snowplow", + name="page_view", + version="1-0-0", + ) + ], + aggregation='counter' +) + +``` + +### Advanced Usage + +Add a `Criteria` to refine the events used to calculate the `Attribute`. For example, if you want to see the number of pageviews on a particular web page on your site. + + +```python +from snowplow_signals import Attribute, Event, Criteria, Criterion + +page_views_attribute = Attribute( + name='page_views_count', + type='int32', + events=[ + Event( + vendor="com.snowplowanalytics.snowplow", + name="page_view", + version="1-0-0", + ) + ], + aggregation='counter', + criteria=Criteria( + all=[ + Criterion( + property="page_title", + operator="=", + value="home_page", + ), + ], + ), +) + +``` + +The table below lists all arguments for an `Attribute`: + +| **Argument Name** | **Description** | **Type** | +| --- | --- | --- | +| `name` | The name of the Attribute | `string` | +| `description` | The description of the Attribute | `string` | +| `type` | The type of the aggregation | One of: `bytes`, `string`, `int32`, `int64`, `double`, `float`, `bool`, `unix_timestamp`, `bytes_list`, `string_list`, `int32_list`, `int64_list`, `double_list`, `float_list`, `bool_list`, `unix_timestamp_list`, | +| `tags` | Metadata for the Attribute | | +| `events` | List of Snowplow Events that the Attribute is calculated on | List of `Event` type; see next section | +| `aggregation` | The aggregation type of the Attribute | One of: `counter`, `sum`, `min`, `max`, `mean`, `first`, `last`, `unique_list` | +| `property` | The property of the event or entity you wish to use in the aggregation | `string` | +| `criteria` | List of `Criteria` to filter the events | List of `Criteria` type | +| `period` | The time period over which the aggregation should be calculated | | + + +### Event Type +The `Event` informs the type of event that the `Attribute` is calculated on. It should be a reference to a Snowplow event that exists on your Snowplow account. + +| **Argument Name** | **Description** | **Type** | +| --- | --- | --- | +| `name` | Name of the event (`event_name` column in atomic.events table) | `string` | +| `vendor` | Vendor of the event (`event_vendor` column in atomic.events table). | `string` | +| `version` | Version of the event (`event_version` column in atomic.events table). | `string` | + +### Criteria +The `Criteria` filters the events used to calculate an `Attribute`. They are made up of individual `Criterion`. + +A `Criteria` accepts one of 2 parameters, both lists of individual `Criterion`: + +- `all`: An array of conditions used to filter the events. All conditions must be met. +- `any`: An array of conditions used to filter the events. At least one of the conditions must be met. + +A `Criterion` specifies the individual filter conditions for an `Attribute` using the following properties. + +| **Argument Name** | **Description** | **Type** | +| --- | --- | --- | +| `property` | The path to the property on the event or entity you wish to filter. | `string` | +| `operator` | The operator used to compare the property to the value. | One of: `=`, `!=`, `<`, `>`, `<=`, `>=`, `like`, `in` | +| `value` | The value to compare the property to. | One of: `str`, `int`, `float`, `bool`, `List[str]`, `List[int]`, `List[float]`, `List[bool]` | + diff --git a/docs/signals/batch_engine/index.md b/docs/signals/batch_engine/index.md new file mode 100644 index 0000000000..f158109e1a --- /dev/null +++ b/docs/signals/batch_engine/index.md @@ -0,0 +1,191 @@ +--- +title: "Batch Engine" +sidebar_position: 40 +description: "In depth explanation on how the Batch Engine works." +sidebar_label: "Batch Engine" +--- + +While many `Attributes` can be computed in stream, those that have to be calculated over a longer period (e.g. a day or more), can only be created "offline" in the warehouse. We call them `Batch Attributes`. + +One advantage of computing batch attributes over stream is that the computation can go back in history based on what you have already available in the atomic events dataset. + +The entity here is typically the user, which may be the `domain_userid` or other Snowplow identifier fields, such as the logged in `user_id`. + +:::info +For now, only the `domain_userid` can be used, but shortly we will extend support for all Snowplow identifiers +::: + +Examples of `Batch Attributes` are typically: +- customer lifetime values +- specific transactions that have or have not happened in the last X number of days +- first or last events a specific user generated or any properties associated to these events + +You may already have tables in your warehouse that contain such computed values, in which case you only have to register them as a batch source to be used by Signals. However, if you don't have them, we have developed a tool called the **`Batch Engine`** to efficiently generate these `Attributes` for you, with the help of a few CLI commands. This way you can avoid having to build complex data models to avoid recalculating the values each time over a very large table, which over time may even be impossible to do, not just costly. + +## How it works +What you need to do first is to define a set of `Attributes` and register them as a `View` through the Python Signals SDK. Then you can use the optional CLI functionality of the SDK to generate a dbt project which will ultimately produce a view-specific attribute table. Then all that's left is to materialize the table, which will mean that Signals will regularly fetch the values from your warehouse table and sends it through the Profiles API. + +## Defining batch attributes +Syntactically speaking, defining batch and stream attributes work the same way. For a general overview of how to do that please refer to the [attributes](/docs/signals/attributes/index.md) section. + +There are 4 main types of attributes that you may likely want to define for batch processing: +1. `Time Windowed Attributes`: Actions that happened in the `last_x_number of days`. Period needs to be defined as timedelta in days. + +2. `Lifetime Attributes`: Calculated over all the available data for the entity. Period needs to be left as None. + +3. `First Touch Attributes`: Events (or properties) that happened for the first time for a given entity. Period needs to be left as None. + +4. `Last Touch Attributes`: Events (or properties) that happened for the last time for a given entity. Period needs to be left as None. + +We have illustrated each of these 4 types with an example block below. + +1. `products_added_to_cart_last_7_days`: This attribute calculates the number of add to cart ecommerce events in the last 7 days + +2. `total_product_price_clv`: This attribute is calculated across the customer lifetime + +3. `first_mkt_source`: This attribute takes the first page_view event and reads the mkt_source property for a specific entity (e.g. domain_userid) + +4. `last_device_class`: This attribute takes the first page_view event and extracts and retrieves the yauaa deviceClass property for a specific entity + +
+Example batch attribute definitions + +Each block creates a single attribute definition including the logic how it should be calculated (its filters and aggregation). + +```python +from snowplow_signals import ( + Attribute, + Criteria, + Criterion, + Event, +) +from datetime import timedelta + +products_added_to_cart_last_7_days = Attribute( + name="products_added_to_cart_last_7_days", + type="string_list", + events=[ + Event( + vendor="com.snowplowanalytics.snowplow", + name="snowplow_ecommerce_action", + version="1-0-2", + ) + ], + aggregation="unique_list", + property="contexts_com_snowplowanalytics_snowplow_ecommerce_product_1[0].name", + criteria=Criteria( + all=[ + Criterion( + property="unstruct_event_com_snowplowanalytics_snowplow_ecommerce_snowplow_ecommerce_action_1:type", + operator="=", + value="add_to_cart", + ), + ], + ), + period=timedelta(days=7), +) + +total_product_price_clv = Attribute( + name="total_product_price_clv", + type="float", + events=[ + Event( + vendor="com.snowplowanalytics.snowplow", + name="snowplow_ecommerce_action", + version="1-0-2", + ) + ], + aggregation="sum", + property="contexts_com_snowplowanalytics_snowplow_ecommerce_product_1[0].price", + criteria=Criteria( + all=[ + Criterion( + property="unstruct_event_com_snowplowanalytics_snowplow_ecommerce_snowplow_ecommerce_action_1:type", + operator="=", + value="add_to_cart" + ) + ] + ), +) + +first_mkt_source = Attribute( + name="first_mkt_source", + type="string", + events=[ + Event( + vendor="com.snowplowanalytics.snowplow", + name="page_view", + version="1-0-0", + ) + ], + aggregation="first", + property="mkt_source", +) + +last_device_class = Attribute( + name="last_device_class", + type="string", + events=[ + Event( + vendor="com.snowplowanalytics.snowplow", + name="page_view", + version="1-0-0", + ) + ], + aggregation="last", + property="contexts_nl_basjes_yauaa_context_1[0]:deviceClass", +) +``` +
+ +## Defining a batch view +The key difference between a standard view and one meant for batch processing is the `offline=True` parameter. This flag indicates that the view’s attributes are computed in the data warehouse. + +```python +from snowplow_signals import View, user_entity + +view = View( + name="batch_ecommerce_attributes", + version=1, + entity=user_entity, + offline=True, + attributes=[ + products_added_to_cart_last_7_days, + total_product_price_clv, + first_mkt_source, + last_device_class + ], +) +``` +## Generating the dbt project +Here we assume you already defined your View(s) related to custom Batch Attributes, you want the Batch Engine to help generate for you. + +It is best to follow our step-by-step tutorial, please check it out [here](/tutorials/snowplow-batch-engine/start/). + +## Understanding the autogenerated data models +The Signals Batch Engine-generated dbt models process the events for Attribute generation, to help you save resources by avoiding unnecessary processing. In each incremental run, only the data that has been loaded since the last time the data models ran get processed and deduplicated. Only the relevant events and properties that are part of the Attribute definition (defined in the same View) are used to create a `filtered_events_table`. Upon successful run, the `snowplow_incremental_manifest` is updated to keep records of where each run left off. + +:::info +For those familiar with existing Snowplow dbt packages, it is worth to note that the incrementalization follows a completely different logic, based on newly loaded data and not by reprocessing sessions as a whole. +::: + +There is a second layer of incremental processing logic dictated by the `daily_aggregation_manifest` table. After the `filtered_events` table is created or updated, the `daily_aggregates` table gets updated with the help of this manifest. It is needed due to late arriving data, which may mean that some days will need to be reprocessed as a whole. For optimization purposes there are variables to fine-tune how this works such as the `snowplow__reprocess_days` and the `snowplow__min_rows_to_process`. + +Finally, the `Attributes` table is generated which is a drop and recompute table, fully updated each time an incremental update runs. This is cost-effective as the data is already pre-aggregated on a daily level. +![](../images/batch_engine_data_models.png) + +## Variables + +```yml title="dbt_project.yml" +snowplow__start_date: '2025-01-01' # date from where it starts looking for events based on both load and derived_tstamp +snowplow__app_id: [] # already gets applied in base_events_this_run +snowplow__backfill_limit_days: 1 # limit backfill increments for the filtered_events_table +snowplow__late_event_lookback_days: 5 # the number of days to allow for late arriving data to be reprocessed fully in the daily aggregate table +snowplow__min_late_events_to_process: 1 # the number of total daily events that have been skipped in previous runs, if it falls within the late_event_lookback_days, if the treshold is reached, those events will be processed in the daily aggregate model +snowplow__allow_refresh: false # if true, the snowplow_incremental_manifest will be dropped when running with a --full-refresh flag +snowplow__dev_target_name: dev +snowplow__databricks_catalog: "hive_metastore" +snowplow__atomic_schema: 'atomic' # Only set if not using 'atomic' schema for Snowplow events data +snowplow__database: # Only set if not using target.database for Snowplow events data -- WILL BE IGNORED FOR DATABRICKS +snowplow__events_table: "events" # Only set if not using 'events' table for Snowplow events data +``` diff --git a/docs/signals/images/batch_engine_data_models.png b/docs/signals/images/batch_engine_data_models.png new file mode 100644 index 0000000000..cc569e0264 Binary files /dev/null and b/docs/signals/images/batch_engine_data_models.png differ diff --git a/docs/signals/images/orgID.png b/docs/signals/images/orgID.png new file mode 100644 index 0000000000..51a470f5b5 Binary files /dev/null and b/docs/signals/images/orgID.png differ diff --git a/docs/signals/images/signals.png b/docs/signals/images/signals.png new file mode 100644 index 0000000000..7ae75d383a Binary files /dev/null and b/docs/signals/images/signals.png differ diff --git a/docs/signals/index.md b/docs/signals/index.md new file mode 100644 index 0000000000..8bd3d77b81 --- /dev/null +++ b/docs/signals/index.md @@ -0,0 +1,101 @@ +--- +title: "Snowplow Signals" +sidebar_position: 8 +description: "An overview of Signals concepts." +sidebar_label: "Signals" +--- + +Snowplow Signals is a personalization engine built on Snowplow's behavioral data pipeline. + +Signals allows you to capture aggregate data attributes about the entities you track events for (such as users, sessions, products, pages, etc), and influence future behavior by sending interventions to users that are currently interacting with those entities. + +The technical core of Signals is the Profile API used for defining and managing attributes and delivering interventions. +The Profile API is hosted in your BDP cloud and can be interacted with using the Signals APIs and SDKs. +Signals also provides infrastructure for working with Snowplow event data in the real-time event stream, and historical data located in your data warehouse. + +![](./images/signals.png) + +Signals allows you to enhance your applications by aggregating historical attributes and providing near real-time visibility into customer behavior. +Use the aggregated attributes and interventions to power in-product personalization and recommendations engines, adaptive user interfaces, and agentic applications like AI copilots and chat-bots. + +## Entities + +The foundation of Signals are entities (distinct from [Snowplow entities](/docs/fundamentals/entities/index.md), but they can be related). + +An entity is the core unit that all the other Signals features relate to, and can be anything with an "identifier" that you can capture in a Snowplow event. + +For example, the simplest entities to think about (and which come predefined when you start with Signals) are concepts like "users", "devices", or "sessions"; these would be entities that you describe in events with the out-of-the-box [user-related fields](/docs/fundamentals/canonical-event/index.md#user-related-fields) like `user_id`, `domain_userid`/`network_userid`, or `domain_sessionid` (respectively). + +You can define any entities you like, and expand this to broader concepts. For example: +- Apps (perhaps described by [`app_id`](/docs/fundamentals/canonical-event/index.md#application-fields)) +- Pages (perhaps [`page_urlpath`](/docs/fundamentals/canonical-event/index.md#platform-specific-fields) or a page identifier captured in a custom entity) +- Products (that you might capture in an [ecommerce entity](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/ecommerce-events/index.md#product) or other custom entity) +- Page/Screen views (as captured in the `web_page` and `screen_view` entities) +- Content categories +- Levels in a game + +Defining an entity and how to identify it unlocks other features so you can do things like compute [attributes](#attributes) for it, or publish [interventions](#interventions) to it. + +## Attributes + +After defining an entity, you can start to calculate attributes for it. + +An attribute represents a specific fact about behavior with an entity and gets defined as part of a [view](#views). + +For example: (attributes for an entity in **bold**) +- _Number of **page** views in the last 7 days:_ counts how many pages a page has received within the past week. +- _Number of pages viewed by a **user** in the last 7 days:_ counts how many pages a user has viewed within the past week. +- _Last product viewed by a **user**:_ identifies the most recent product a user interacted with. +- _Last product sold from **product category**:_ identifies the most recent product any user has bought within a product category. +- _Previous purchases by **user**:_ provides a record of the user's past transactions. + +All attributes get defined as part of a [view](#views), which ties them to a specific entity and source, defining how their values get updated. + +You can also set them manually via the APIs, or dynamically via interventions. + +Read more [about attributes](/docs/signals/attributes/index.md). + +### Views + +A View is a versioned collection of attributes associated with a specific entity that are populated from the same source. + +You can picture the result of a View as a table of attributes for an entity instance. + +For example, from the [previous example attributes](#attributes) for a user-entity keyed by `user_id`: + +| `user_id` | `number_of_pageviews` | `last_product_viewed` | `previous_purchases` | +|-----------|-----------------------|-----------------------|---------------------------| +| `abc123` | 5 | Red Shoes | [`Blue Shoes`, `Red Hat`] | + +The attributes of a view can be set to expire for instances if they aren't updated after a certain period of time. + +Each view can be associated with metadata such as an owner, description, and tags. + +When you're happy with a version of a View definition, you can associate it with a service to be consistently requested via the API for personalization. + +Read more [about views](/docs/signals/views_services/index.md). + + +### Services + +A Service is a collection of [views](#views) that are grouped to make the retrieval of attributes simpler. + +They allow you to retrieve attributes in bulk from multiple views, that are each pinned to specific versions so you can ensure the returned values are consistent with what you expect. +This allows you to freely iterate on your view/attribute definitions without impacting production applications that rely on your attributes, and letting you migrate to new versions when ready. + +Read more [about services](/docs/signals/views_services/index.md). + +## Interventions + +Once an entity is defined in Signals you can start to retrieve interventions for it, and start publishing to them. + +An intervention describes an action that can be performed for a user to achieve a more successful result. + +User devices and your own systems can request interventions for a list of specific entities, which are then delivered in real-time as they are published. +You can publish interventions manually using the API, or define them to trigger automatically when [attributes](#attributes) get updated and meet specific criteria. +There are built-in operations that interventions can perform or that can be handled by Signals SDKs, but the contents of an intervention can contain custom data to use however you need to, and can include current attribute values for dynamic, personalized, actions using the latest real-time data. + +For example, a user can subscribe to interventions for their own `domain_userid`, the current `app_id`, the current `page`, and the current `product`, and any interventions published targeting any of those entities get received. +This enables both individual-level and broadcast-level messaging, so you can offer a specific user a personalized message, while also notifying all users on a specific product page that limited stock is selling fast. + + diff --git a/docs/signals/quickstart/index.md b/docs/signals/quickstart/index.md new file mode 100644 index 0000000000..42dde383ed --- /dev/null +++ b/docs/signals/quickstart/index.md @@ -0,0 +1,168 @@ +--- +title: "Signals Quickstart" +sidebar_position: 10 +description: "An overview of Signals concepts." +sidebar_label: "Quickstart Guide" +--- +```mdx-code-block +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +``` + +:::note +You can try an interactive version of this Quickstart on Google Colab [here](https://colab.research.google.com/drive/1ExqheS4lIuJRs0wk0B6sxaYfnZGcTYUv). +::: + + +Welcome to the Snowplow Signals Quickstart! This guide will walk you through the steps to set up and use Snowplow Signals to define attributes, create views, and retrieve user features. By the end of this guide, you'll have a working setup to personalize your applications using Snowplow Signals. + +1. **Install and Set Up the SDK**: Get started with the Snowplow Signals SDK. +2. **Define an Attribute**: Learn how to define stream user behavior attributes. +3. **Create and Test a View**: Combine attributes into a view and test it. +4. **Deploy a View**: Push a view to the Profile API +5. **Retrieve Attributes**: Fetch user features from the Profile API. +Steps 1-4 are the Signals configuration. Step 5 shows how to start using the stored attributes. +## Step 1: Installation and Setup +The Snowplow Signals SDK allows you to define attributes, create views, and retrieve user features. It requires Python 3.12 or above. + +Install the SDK using pip: + +```bash +$ pip install snowplow-signals +``` + +To connect to your Signals deployment, you will need 4 values. + +An API Key Id and the corresponding API Key (secret), which are generated from the [credentials section](https://console.snowplowanalytics.com/credentials) in BDP Console. + +The organization ID, which can be retrieved from the URL immediately following the .com when visiting BDP Console: + +![](../images/orgID.png) + + +```python +from snowplow_signals import Signals +signals = Signals( + api_url="API_URL", + api_key="API KEY", + api_key_id="API_KEY_ID", + org_id="ORG_ID", +) +``` + +## Step 2: Define an `Attribute` + +An `Attribute` represents a specific fact about a user's behavior. For example, you can define an attribute to count the number of `page_view` events a user has made. + +```python +from snowplow_signals import Attribute, Event + +page_view_count = Attribute( + name="page_view_count", + type="int32", + events=[ + Event( + vendor="com.snowplowanalytics.snowplow", + name="page_view", + version="1-0-0", + ) + ], + aggregation="counter" +) +``` +You can refine to your attributes by adding `Criteria` to filter for specific events. For example: + +```python +from snowplow_signals import Attribute, Event, Criteria, Criterion + +products_added_to_cart_feature = Attribute( + name="products_added_to_cart", + type="string_list", + events=[ + Event( + vendor="com.snowplowanalytics.snowplow.ecommerce", + name="snowplow_ecommerce_action", + version="1-0-2", + ) + ], + aggregation="unique_list", + property="contexts_com_snowplowanalytics_snowplow_ecommerce_product_1[0].name", + criteria=Criteria( + all=[ + Criterion( + property="unstruct_event_com_snowplowanalytics_snowplow_ecommerce_snowplow_ecommerce_action_1:type", + operator="=", + value="add_to_cart", + ), + ], + ), +) +``` + +## Step 3: Create and test a `View` + +A `View` is a collection of attributes that share a common entity (e.g., session or user). Here's how to create a view with the attributes we defined earlier: + +```python +from snowplow_signals import View, domain_sessionid + +my_attribute_view = View( + name="my_attribute_view", + version=1, + entity=domain_sessionid, + attributes=[ + page_view_count, + products_added_to_cart_feature, + ], + owner="user@company.com", +) +``` + +Before deploying the view, you can test it on the atomic events table from the past hour: + + +```python +data = sp_signals.test( + view=view, + app_ids=["website"], +) +print(data) +``` + +Example Output + +| **domain_sessionid** | **page_view_count** | **products_added_to_cart** | +|----------------------|--------------------|-----------------------------| +| xyz | 5 | [`red_hat`, `blue_shoes`] | +| abc | 3 | [`green_trainers`] | + +:::warning +**Note:** You can filter on specific app_ids during testing. To avoid unnecessary compute, the streaming engine is typically configured to process only a subset of relevant app_ids. While you may be able to test using any app_id, bear in mind that data retrieval might not return expected results if that app_id isn't included in the streaming engine’s configuration. +::: + +## Step 4: Deploy a `View` to Signals +Once you're satisfied with the View, deploy it to the API using the `apply` method: + +```python +signals.apply([my_attribute_view]) +``` + +This makes the View live, and events will start being processed based on the defined attributes. + +## Step 5: Retrieve `Attributes` from Signals + +Now that events are being processed, you can retrieve user features from the API: + +```python +response = sp_signals.get_online_attributes( + source=my_attribute_view, + identifiers="abc-123", +) +``` + +Expected Output + +| **domain_sessionid** | **page_view_count** | **products_added_to_cart** | +|-----------------------|---------------------|-----------------------------| +| abc-123 | 3 | [`blue_shoes`] | diff --git a/docs/signals/sources/batch.md b/docs/signals/sources/batch.md new file mode 100644 index 0000000000..00d440777e --- /dev/null +++ b/docs/signals/sources/batch.md @@ -0,0 +1,75 @@ +--- +title: "Batch Sources" +sidebar_position: 30 +description: "Batch Sources." +sidebar_label: "Batch Sources" +--- + +In addition to stream sources, Signals allows you to create attributes based on data stored in your warehouse. Batch sources are ideal for metrics calculated over longer periods of time, such as: + +- Previous purchase history +- Number of site visits in the last 7 days +- Average session length + +Batch sources can be defined in two ways: + +1. Using existing tables in your warehouse. +2. Automatically generating tables via the dbt autogen CLI. + + +## Using Existing Tables + +### Defining a Batch Source +To use an existing table in your warehouse, first define the connection to the table. Here's an example: + +```python +data_source = BatchSource( + name="ecommerce_transaction_interactions_source", + database="SNOWPLOW_DEV1", + schema="SIGNALS", + table="SNOWPLOW_ECOMMERCE_TRANSACTION_INTERACTIONS_FEATURES", + timestamp_field="UPDATED_AT", +) +``` + +### Defining a View + +Once the `BatchSource` is defined, you can create a `View` by specifying the fields (columns) you want to use from the table. Here's an example: + + +```python +from snowplow_signals import View, domain_userid, Field + +view = View( + name="ecommerce_transaction_interactions_attributes", + version=1, + entity=domain_userid, + fields=[ + Field( + name="TOTAL_TRANSACTIONS", + type="int32", + ), + Field( + name="TOTAL_REVENUE", + type="int32", + ), + Field( + name="AVG_TRANSACTION_REVENUE", + type="int32", + ), + ], + batch_source=data_source, + owner="user@company.com", +) +``` + +### Apply the View + +Finally, apply the View to make the attributes available to your app + +```python +sp_signals.apply([view]) +``` + +Once applied, the attributes defined in the `View` will be available for use in your app. + diff --git a/docs/signals/sources/index.md b/docs/signals/sources/index.md new file mode 100644 index 0000000000..60a7ec6ba4 --- /dev/null +++ b/docs/signals/sources/index.md @@ -0,0 +1,16 @@ +--- +title: "Sources" +sidebar_position: 10 +description: "Sources." +sidebar_label: "Sources" +--- + +A `Source` defines how an `Attribute` is calculated. There are two types of sources: + +- Stream: Attributes are calculated in real time, making them ideal for instant personalization and session-based metrics. This is the default stream type. +- Batch: Attributes are calculated using historical data stored in your warehouse, suitable for metrics over longer time periods. + +### When to use each source + +- Use Stream Sources for real-time use cases, such as tracking the latest product a user viewed or the number of page views in a session. +- Use Batch Sources for historical analysis, such as calculating a user's purchase history or average session length. diff --git a/docs/signals/sources/stream.md b/docs/signals/sources/stream.md new file mode 100644 index 0000000000..f759fd31bc --- /dev/null +++ b/docs/signals/sources/stream.md @@ -0,0 +1,34 @@ +--- +title: "Stream Sources" +sidebar_position: 20 +description: "Stream" +sidebar_label: "Stream Sources" +--- + +By default, attributes are calculated in stream. This ensures they are available for near real-time personalization. Stream sources are automatically created in the Profile API when you apply a `View`. + +You may like to configure common `Stream` source attributes such as: + +- Latest product viewed +- Search history +- Number of page views in a session + +### Stream Source + +When you apply a `View`, a stream source is automatically created. This source calculates the attributes defined in the `View` in real-time. + +Here's an example: +```python +view = View( + name="view", + version=1, + entity=domain_sessionid, + attributes=[page_view_count], + owner="user@company.com", +) + +sp_signals.apply([view]) #Stream Source created +``` + +Once applied, the stream source begins calculating the attributes in real-time. + diff --git a/docs/signals/views_services/index.md b/docs/signals/views_services/index.md new file mode 100644 index 0000000000..974822825e --- /dev/null +++ b/docs/signals/views_services/index.md @@ -0,0 +1,133 @@ +--- +title: "Views and Services" +sidebar_position: 30 +description: "Views and Services." +sidebar_label: "Views and Services" +--- + +To access attributes, you need to define a `View` and optionally group multiple views into a `Service`. This guide explains how to define views and services, apply them to your deployment, and retrieve calculated values. + + +### What is a View? +A `View` is a versioned collection of attributes grouped by a common `Entity` (e.g., `session_id` or `user_id`). Once defined, a `View` allows you to retrieve the calculated values of the attributes it contains. + +### What is a Service? +A `Service` is a collection of views that streamlines the retrieval of multiple views. By grouping related views into a `Service`, you can efficiently manage and access user insights, making it easier to personalize applications and analyze behavior. + + +### Defining a View +You can define a `View` by passing in a list of previously defined attributes. Here's an example: + +```python +from snowplow_signals import View, domain_sessionid + +my_attribute_view = View( + name="my_attribute_view", + version=1, + entity=domain_sessionid, + attributes=[ + #Previously defined Attributes + page_view_count, + products_added_to_cart_feature, + ], + owner="user@company.com", +) +``` + +### Testing a View +To understand what the output of a `View` will look like, use the `test` method with the `Signals` class. This will output a table of `Attributes` from your `atomic` events table. + +```python +# Assuming signals object has been instantiated using the Signals() class + +test_data = sp_signals.test( + view=my_attribute_view, + app_ids=["website"] # The app id in your Snowplow Events +) + +``` + +### View Properties + +The `View` has the following properties: + + +| **Argument Name** | **Description** | **Type** | +| --- | --- | --- | +| `name` | The name of the View | `string` | +| `version` | The version of the View | `int` | +| `entity` | The entity associated with the View | `Entity` | +| `ttl` | The amount of time this group of attributes lives. If not specified, the entity's ttl is used or the ttl is not limited. | `timedelta` | +| `batch_source` | The data source for the View | `BatchSource` | +| `online` | Whether online retrieval is enabled (`True`) or not (`False`) | `bool` | +| `offline` | Whether the View is calculated in the warehouse (`True`) or in real-time (`False`) | `bool` | +| `description` | The description of the View | `string` | +| `tags` | The metadata of the View | `dict` | +| `owner` | The owner of the feature view, typically the email of the primary maintainer. | `string` | +| `fields` | The list of table columns that are part of this view during materialization. | `Field` | +| `attributes` | The list of attributes that will be calculated from events as part of this view. | `Attribute` | + + +### View computation types +The method of calculating and serving attributes related to a specific View depends on a specific combination of property values, illustrated in the below matrix: + +| | Offline = false | Offline = true and has attributes | Offline = True and has no attributes | +|---|---|---|---| +| **Online = false** | Attributes are not computed anywhere | Attributes computed through the Batch Engine in the warehouse but not yet materialized | Table pre-computed without Batch Engine and only in the warehouse | +| **Online = true** | Attributes computed in stream | Attributes computed through the Batch Engine and materialized into Signals | Table materialized into Signals (if it has a batch source configured) | + + +### Services +A `Service` groups multiple `Views` together, allowing you to retrieve calculated values from all the `Views` in the `Service`. Here's an example: + +```python +from snowplow_signals import Service + +my_service = Service( + name='my_service', + description='A collection of views', + views=[ + # Previously defined Views + my_attribute_view, + another_view + ] +) + +``` + +### Applying Views and Services + +To begin calculating your `Attributes`, you need to apply the `Views` or `Services` to your `Signals` deployment using the `apply` method: + + +```python +# Assuming signals object has been instantiated using the Signals() class + +sp_signals.apply([ + my_service, + my_other_service + ]) +``` + +Once applied, the attributes within these Views and Services will be calculated. + + +### Retrieving Calculated Values + +To access the calculated values, use the `get_online_attributes` method. Here's an example: + +```python +# Assuming signals object has been instantiated using the Signals() class + +calculated_values = sp_signals.get_online_attributes( + source=my_service, + identifiers="abc-123", +) + +print(calculated_values) +``` + +:::warning +**Note:** While you can filter on specific app_ids during testing, both the streaming and batch engines may be configured to process only a subset of relevant app_ids to avoid unnecessary compute. As a result, testing with an arbitrary app_id may not yield expected data if it isn’t included in the configured subset. +::: + diff --git a/docs/sources/first-party-tracking/index.md b/docs/sources/first-party-tracking/index.md index e9b7e3f1b7..757d33f515 100644 --- a/docs/sources/first-party-tracking/index.md +++ b/docs/sources/first-party-tracking/index.md @@ -16,7 +16,7 @@ When your collector domain (e.g. `collector.snwplow.net`) does not match your pr With first-party tracking, you can configure a custom collector domain (e.g. `c.flowershop.ai`) to match your primary domain (e.g. `flowershop.ai`), sidestepping these limitations. -Note that in light of the [latest ITP restrictions](https://webkit.org/tracking-prevention/#cname-and-third-party-ip-address-cloaking-defense), you will also need to [use an ID service](/docs/sources/trackers/javascript-trackers/web-tracker/browsers/index.md#itp-mitigation) to fully persist the cookies. +Note that in light of the [latest ITP restrictions](https://webkit.org/tracking-prevention/#cname-and-third-party-ip-address-cloaking-defense), you will also need to [use a Cookie Extension service](/docs/events/cookie-extension/index.md) to fully persist the cookies. :::info @@ -46,8 +46,8 @@ For Snowplow collector to be able to set the cookie, the cookie domain must be a Here are a few examples: -| Collector domain | Cookie domain | Cookie available on | -|:----------------------|:--------------------|:-----------------------------------------------| +| Collector domain | Cookie domain | Cookie available on | +| :-------------------- | :------------------ | :------------------------------------------------------- | | `t.flowershop.ai` | `flowershop.ai` | `flowershop.ai`,
`app.flowershop.ai`, etc | | `c.app.flowershop.ai` | `app.flowershop.ai` | `app.flowershop.ai`,
`beta.app.flowershop.ai`, etc | diff --git a/docs/sources/index.md b/docs/sources/index.md index 1b1cf7bcf8..d5aebc2b9a 100644 --- a/docs/sources/index.md +++ b/docs/sources/index.md @@ -12,7 +12,7 @@ For tracking from third-party applications, use our [webhooks](/docs/sources/web -
+
adjust AMP Android diff --git a/docs/sources/trackers/c-tracker/tracking-specific-events/index.md b/docs/sources/trackers/c-tracker/tracking-specific-events/index.md index e343e93d30..1f17f10e91 100644 --- a/docs/sources/trackers/c-tracker/tracking-specific-events/index.md +++ b/docs/sources/trackers/c-tracker/tracking-specific-events/index.md @@ -17,7 +17,7 @@ The tracker provides the following event classes for tracking events out of the | `ScreenViewEvent` | Tracks the user viewing a screen within the application | | `TimingEvent` | Tracks a timing event | -Snowplow events are all processed into the same format, regardless of the event type (and regardless of the tracker language used). Read about the different properties and fields of events in the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +Snowplow events are all processed into the same format, regardless of the event type (and regardless of the tracker language used). Read about the different properties and fields of events in the [Snowplow Tracker Protocol](/docs/events/index.md). ## Custom event context diff --git a/docs/sources/trackers/flutter-tracker/initialization-and-configuration/index.md b/docs/sources/trackers/flutter-tracker/initialization-and-configuration/index.md index a8e2c25b29..36257ac294 100644 --- a/docs/sources/trackers/flutter-tracker/initialization-and-configuration/index.md +++ b/docs/sources/trackers/flutter-tracker/initialization-and-configuration/index.md @@ -103,7 +103,7 @@ Some of the properties are only configurable on iOS and Android and are automati | `screenViewport` | `Size?` | The screen viewport. | ✔ | ✔ | Non-configurable, auto-assigned. | | | `colorDepth` | `double?` | The color depth. | ✔ | ✔ | Non-configurable, auto-assigned. | | -The configured attributes are mapped to Snowplow event properties described in the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). They are mapped as follows: +The configured attributes are mapped to Snowplow event properties described in the [Snowplow Tracker Protocol](/docs/events/index.md). They are mapped as follows: | Attribute | Event Property | |---------------------------|---------------------| diff --git a/docs/sources/trackers/flutter-tracker/tracking-events/index.md b/docs/sources/trackers/flutter-tracker/tracking-events/index.md index 3615b2f4e1..98e76db64b 100644 --- a/docs/sources/trackers/flutter-tracker/tracking-events/index.md +++ b/docs/sources/trackers/flutter-tracker/tracking-events/index.md @@ -69,7 +69,7 @@ Event classes supported by the Flutter Tracker: All the methods share common features and parameters. Every type of event can have an optional context added. See the [next page](/docs/sources/trackers/flutter-tracker/adding-data/index.md) to learn about adding extra data to events. It's important to understand how event context works, as it is one of the most powerful Snowplow features. Adding event context is a way to add depth, richness and value to all of your events. -Snowplow events are all processed into the same format, regardless of the event type (and regardless of the tracker language used). Read about the different properties and fields of events in the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +Snowplow events are all processed into the same format, regardless of the event type (and regardless of the tracker language used). Read about the different properties and fields of events in the [Snowplow Tracker Protocol](/docs/events/index.md). We will first discuss the custom event types, followed by the out-of-the-box event types. Note that you can also design and create your own page view, or screen view, using `selfDescribing`, to fit your business needs better. The out-of-the-box event types are provided so you can get started with generating event data quickly. @@ -182,11 +182,11 @@ Concretely, it consists of the following metrics: 3. Number of list items scrolled out of all list items (requires some manual tracking). 4. Scroll depth in pixels (requires some manual tracking). -This information is attached using a [`screen_summary` context entity](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md#screen-summary-entity) to the following events: +This information is attached using a [`screen_summary` context entity](/docs/events/ootb-data/page-activity-tracking/index.md#screen-summary-entity) to the following events: -1. [`screen_end` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md#screen-end-event) that is automatically tracked before a new screen view event. -2. [`application_background` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#background-event). -3. [`application_foreground` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#foreground-event). +1. [`screen_end` event](/docs/events/ootb-data/page-activity-tracking/index.md#screen-end-event) that is automatically tracked before a new screen view event. +2. [`application_background` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#background-event). +3. [`application_foreground` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#foreground-event). Screen engagement tracking is enabled by default, but can be configured using the `TrackerConfiguration.screenEngagementAutotracking` option. diff --git a/docs/sources/trackers/google-amp-tracker/index.md b/docs/sources/trackers/google-amp-tracker/index.md index 27d8b864b4..210791d9e5 100644 --- a/docs/sources/trackers/google-amp-tracker/index.md +++ b/docs/sources/trackers/google-amp-tracker/index.md @@ -91,7 +91,7 @@ Notes: ### `userId` -Specify the optional `"userId"` var to set the uid/user_id [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md#user-related-parameters) field. +Specify the optional `"userId"` var to set the uid/user_id [Snowplow Tracker Protocol](/docs/events/index.md#user-related-parameters) field. ```javascript "vars": { @@ -101,7 +101,7 @@ Specify the optional `"userId"` var to set the uid/user_id [Snowplow Tracker Pr ### `nameTracker` -Specify the optional "nameTracker" var to set the tna/name_tracker [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters) field. +Specify the optional "nameTracker" var to set the tna/name_tracker [Snowplow Tracker Protocol](/docs/events/index.md#application-parameters) field. ```javascript "vars": { diff --git a/docs/sources/trackers/google-tag-manager/settings-template/index.md b/docs/sources/trackers/google-tag-manager/settings-template/index.md index 9f1acba0ce..4877117af0 100644 --- a/docs/sources/trackers/google-tag-manager/settings-template/index.md +++ b/docs/sources/trackers/google-tag-manager/settings-template/index.md @@ -86,6 +86,10 @@ This setting disables client-side user identifiers but tracks session informatio See [here](/docs/resources/recipes-tutorials/recipe-anonymous-tracking/index.md) for more information on anonymous tracking. +#### Cookie Extension Service + +This allows you to set the endpoint for the [Cookie Extension Service](/docs/events/cookie-extension/index.md). + ## Cookie Settings ### State Storage Strategy @@ -119,6 +123,10 @@ This setting allows you to specify the SameSite attribute for the Snowplow track This setting allows you to specify the timeout for the session cookie. By default, the session cookie will expire after 30 minutes of inactivity. +### Synchronously Write Cookies + +This setting allows you to specify whether the Snowplow tracker should [write cookies synchronously](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#synchronous-cookie-writes). By default, the tracker will write cookies asynchronously. + ## Dispatching ### Common @@ -159,6 +167,12 @@ This setting allows you to specify the maximum size of the payload that will be If an event is generated that is over the maximum payload size, the event will bypass the buffer and be sent immediately to the collector. This means that if it fails, it will not be retried. +#### Enable keepalive + +This setting allows you to enable or disable the [keepalive](/docs/sources/trackers/javascript-trackers/web-tracker/configuring-how-events-sent/index.md#keepalive-option-for-collector-requests) feature. This will enable requests to continue to be sent, even if the user navigates away from the page that sent the request. + +Defaults to `false`. + ## Predefined Contexts Predefined contexts provide additional metadata for your Snowplow events. By including these contexts, you can capture common data points like device information, session details, or geolocation without having to define them manually. @@ -170,6 +184,6 @@ Available predefined contexts are: | `webPage` | Information about the web page where the event occurred. | [Web Page tracking](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/page-views/index.md#webpage-page-view-id-context-entity) | | `gaCookies` | Information about the Google Analytics cookies. | [Google Analytics Cookies Plugin](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ga-cookies/index.md) | | `clientHints` | Information about the client's device. | [Client Hints Plugin](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/client-hints/index.md) | -| `geolocation` | Information about the client's geolocation. | [Geolocation](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/geolocation/index.md) | -| `session` | Information about the user session. | [Session](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/user-and-session-identification/index.md#client-session-context-entity) | +| `geolocation` | Information about the client's geolocation. | [Geolocation](/docs/events/ootb-data/geolocation/index.md) | +| `session` | Information about the user session. | [Session](/docs/events/ootb-data/user-and-session-identification/index.md#client-session-context-entity) | | `performanceNavigationTiming` | Retrieves data from the [PerformanceNavigationTiming](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming) API. | [Performance Navigation Timing](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/timings/index.md) | diff --git a/docs/sources/trackers/google-tag-manager/snowplow-template/index.md b/docs/sources/trackers/google-tag-manager/snowplow-template/index.md index 7ed7205e92..f55b18081d 100644 --- a/docs/sources/trackers/google-tag-manager/snowplow-template/index.md +++ b/docs/sources/trackers/google-tag-manager/snowplow-template/index.md @@ -3,7 +3,7 @@ title: Snowplow Template sidebar_position: 200 --- -This template implements the [Snowplow JavaScript tracker](/docs/sources/trackers/javascript-trackers/web-tracker/index.md) for Google Tag Manager. It allows for the sending of [Snowplow events](docs/sources/trackers/snowplow-tracker-protocol/index.md) from your website to your Snowplow collector. +This template implements the [Snowplow JavaScript tracker](/docs/sources/trackers/javascript-trackers/web-tracker/index.md) for Google Tag Manager. It allows for the sending of [Snowplow events](docs/events/index.md) from your website to your Snowplow collector. Tag Types are the kinds of events that can be tracked with the Snowplow v4 Tag Template. Each tag type has its own set of options and parameters that can be configured. @@ -217,7 +217,7 @@ The Errors tracker tag provides a way to manually track any errors that occur on ## Page View -You can provide a `Custom Page Title` if you wish, and you can add a [custom context](/docs/sources/trackers/snowplow-tracker-protocol/custom-events/context-entities/index.md) to the request, as also described [here](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/page-views/index.md#tracking-a-page-view). +You can provide a `Custom Page Title` if you wish, and you can add a [custom context](/docs/events/custom-events/context-entities/index.md) to the request, as also described [here](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/page-views/index.md#tracking-a-page-view). If you enable `Page Activity Tracking`, page pings will be sent at intervals that you can specify. diff --git a/docs/sources/trackers/index.md b/docs/sources/trackers/index.md index 29aba33576..7c0ba4cd5a 100644 --- a/docs/sources/trackers/index.md +++ b/docs/sources/trackers/index.md @@ -17,18 +17,18 @@ For tracking events from third-party applications, use our [webhooks](/docs/sour | Tracker | Language | Used in | [Snowtype](/docs/data-product-studio/snowtype/index.md)? | Supported [data models](/docs/modeling-your-data/modeling-your-data-with-dbt/index.md) | GitHub | Installed using | | ----------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| [Web](/docs/sources/trackers/javascript-trackers/web-tracker/index.md) (JavaScript) | TypeScript, JavaScript | Web | ✅ | Unified Digital, Media Player, Ecommerce | [snowplow-javascript-tracker](https://github.com/snowplow/snowplow-javascript-tracker) | Script tag | -| [Web](/docs/sources/trackers/javascript-trackers/web-tracker/index.md) (Browser) | TypeScript, JavaScript | Web | ✅ | Unified Digital, Media Player, Ecommerce | [snowplow-javascript-tracker](https://github.com/snowplow/snowplow-javascript-tracker) | [npm](https://www.npmjs.com/package/@snowplow/browser-tracker), yarn, or pnpm | -| [Google Tag Manager](/docs/sources/trackers/google-tag-manager/index.md) | JavaScript | Web | ❌ | Unified Digital, Ecommerce | n/a | [Tag Template Gallery](https://tagmanager.google.com/gallery/#/owners/snowplow/templates/snowplow-gtm-tag-template-v4) | +| [Web](/docs/sources/trackers/javascript-trackers/web-tracker/index.md) (JavaScript) | TypeScript, JavaScript | Web | ✅ | Unified Digital, Attribution, Media Player, Ecommerce | [snowplow-javascript-tracker](https://github.com/snowplow/snowplow-javascript-tracker) | Script tag | +| [Web](/docs/sources/trackers/javascript-trackers/web-tracker/index.md) (Browser) | TypeScript, JavaScript | Web | ✅ | Unified Digital, Attribution, Media Player, Ecommerce | [snowplow-javascript-tracker](https://github.com/snowplow/snowplow-javascript-tracker) | [npm](https://www.npmjs.com/package/@snowplow/browser-tracker), yarn, or pnpm | +| [Google Tag Manager](/docs/sources/trackers/google-tag-manager/index.md) | JavaScript | Web | ❌ | Unified Digital, Attribution, Ecommerce | n/a | [Tag Template Gallery](https://tagmanager.google.com/gallery/#/owners/snowplow/templates/snowplow-gtm-tag-template-v4) | | [Google AMP](/docs/sources/trackers/google-amp-tracker/index.md) | HTML | AMP HTML webpages | ❌ | | n/a | Script tag | | [Pixel](/docs/sources/trackers/pixel-tracker/index.md) | HTML | Email, web environments where JavaScript is unavailable | ❌ | | n/a | Script tag | | [Google Analytics Plugin](/docs/sources/trackers/google-analytics-plugin/index.md) | HTML | Web | ❌ | | n/a | Script tag | -| [Android](/docs/sources/trackers/mobile-trackers/index.md) | Kotlin, Java | Mobile | ✅ | Unified Digital, Media Player, Ecommerce | [snowplow-android-tracker](https://github.com/snowplow/snowplow-android-tracker) | [Maven](https://mvnrepository.com/artifact/com.snowplowanalytics/snowplow-android-tracker) | -| [iOS](/docs/sources/trackers/mobile-trackers/index.md) | Swift, Objective-C | Mobile (iOS), macOS, tvOS, watchOS, visionOS | ✅ | Unified Digital, Media Player, Ecommerce | [snowplow-ios-tracker](https://github.com/snowplow/snowplow-ios-tracker) | SPM or [Cocoapods](https://cocoapods.org/pods/SnowplowTracker) | -| [React Native](/docs/sources/trackers/react-native-tracker/index.md) | TypeScript, JavaScript | Mobile | ✅ | Unified Digital | [snowplow-javascript-tracker](https://github.com/snowplow/snowplow-javascript-tracker) | [npm](https://www.npmjs.com/package/@snowplow/react-native-tracker) | -| [Flutter](/docs/sources/trackers/flutter-tracker/index.md) | Dart | Mobile | ✅ | Unified Digital, Media Player | [snowplow-flutter-tracker](https://github.com/snowplow/snowplow-flutter-tracker) | [pub.dev](https://pub.dev/packages/snowplow_tracker) | +| [Android](/docs/sources/trackers/mobile-trackers/index.md) | Kotlin, Java | Mobile | ✅ | Unified Digital, Attribution, Media Player, Ecommerce | [snowplow-android-tracker](https://github.com/snowplow/snowplow-android-tracker) | [Maven](https://mvnrepository.com/artifact/com.snowplowanalytics/snowplow-android-tracker) | +| [iOS](/docs/sources/trackers/mobile-trackers/index.md) | Swift, Objective-C | Mobile (iOS), macOS, tvOS, watchOS, visionOS | ✅ | Unified Digital, Attribution, Media Player, Ecommerce | [snowplow-ios-tracker](https://github.com/snowplow/snowplow-ios-tracker) | SPM or [Cocoapods](https://cocoapods.org/pods/SnowplowTracker) | +| [React Native](/docs/sources/trackers/react-native-tracker/index.md) | TypeScript, JavaScript | Mobile | ✅ | Unified Digital, Attribution | [snowplow-javascript-tracker](https://github.com/snowplow/snowplow-javascript-tracker) | [npm](https://www.npmjs.com/package/@snowplow/react-native-tracker) | +| [Flutter](/docs/sources/trackers/flutter-tracker/index.md) | Dart | Mobile | ✅ | Unified Digital, Attribution, Media Player | [snowplow-flutter-tracker](https://github.com/snowplow/snowplow-flutter-tracker) | [pub.dev](https://pub.dev/packages/snowplow_tracker) | | [Roku](/docs/sources/trackers/roku-tracker/index.md) | BrightScript, BrighterScript | Media player applications | ❌ | Media Player | [snowplow-roku-tracker](https://github.com/snowplow/snowplow-roku-tracker) | [npm](https://www.npmjs.com/package/@snowplow/roku-tracker) | -| [WebView](/docs/sources/trackers/webview-tracker/index.md) | TypeScript, JavaScript | Hybrid mobile applications | ❌ | Unified Digital | [snowplow-webview-tracker](https://github.com/snowplow/snowplow-webview-tracker) | [npm](https://www.npmjs.com/package/@snowplow/webview-tracker) or script tag | +| [WebView](/docs/sources/trackers/webview-tracker/index.md) | TypeScript, JavaScript | Hybrid mobile applications | ❌ | Unified Digital, Attribution | [snowplow-webview-tracker](https://github.com/snowplow/snowplow-webview-tracker) | [npm](https://www.npmjs.com/package/@snowplow/webview-tracker) or script tag | ## Server-side trackers diff --git a/docs/sources/trackers/java-tracker/previous-versions/java-tracker-v0-11/initialization/index.md b/docs/sources/trackers/java-tracker/previous-versions/java-tracker-v0-11/initialization/index.md index da26e5da16..d4881a03b7 100644 --- a/docs/sources/trackers/java-tracker/previous-versions/java-tracker-v0-11/initialization/index.md +++ b/docs/sources/trackers/java-tracker/previous-versions/java-tracker-v0-11/initialization/index.md @@ -86,4 +86,4 @@ Tracker tracker = new Tracker.TrackerBuilder(emitter, "AF003", "sp") .build(); ``` -For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md#common-parameters). +For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md#common-parameters). diff --git a/docs/sources/trackers/java-tracker/previous-versions/java-tracker-v0-12/tracking-events/index.md b/docs/sources/trackers/java-tracker/previous-versions/java-tracker-v0-12/tracking-events/index.md index ec35624e6d..39c727d02a 100644 --- a/docs/sources/trackers/java-tracker/previous-versions/java-tracker-v0-12/tracking-events/index.md +++ b/docs/sources/trackers/java-tracker/previous-versions/java-tracker-v0-12/tracking-events/index.md @@ -19,7 +19,7 @@ The Java tracker makes it easy to track different kinds of data. We provide a ra Every tracked event payload has a unique `event_id` UUID string. Other ubiquitous properties include the `name_tracker` (`trackerNamespace`) and `app_id` (`appId`) set when the `Tracker` was initialized. From version 0.12 onwards, `Tracker.track()` returns the payload's `eventId`. -Snowplow events have a defined structure and [protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md) that is identical regardless of the tracker used. A minimal payload - the raw event - is sent from the tracker to your collector. The raw event is [enriched](/docs/pipeline/enrichments/index.md) as it passes through your pipeline. By the time the event arrives in your data storage, depending which [enrichments](/docs/pipeline/enrichments/available-enrichments/index.md) you have enabled, it will have gained different kinds of metadata, and have many more fields than it started with. The default Java tracker event fields are shown [here](/docs/sources/trackers/java-tracker/previous-versions/java-tracker-v0-12/what-do-java-tracker-events-look-like/index.md). +Snowplow events have a defined structure and [protocol](/docs/events/index.md) that is identical regardless of the tracker used. A minimal payload - the raw event - is sent from the tracker to your collector. The raw event is [enriched](/docs/pipeline/enrichments/index.md) as it passes through your pipeline. By the time the event arrives in your data storage, depending which [enrichments](/docs/pipeline/enrichments/available-enrichments/index.md) you have enabled, it will have gained different kinds of metadata, and have many more fields than it started with. The default Java tracker event fields are shown [here](/docs/sources/trackers/java-tracker/previous-versions/java-tracker-v0-12/what-do-java-tracker-events-look-like/index.md). The [Java tracker Github repository](https://github.com/snowplow/snowplow-java-tracker) includes a mini demo, "simple-console". The demo sends one event of each type to your event collector. diff --git a/docs/sources/trackers/java-tracker/tracking-events/index.md b/docs/sources/trackers/java-tracker/tracking-events/index.md index e5d57efaee..5e086d0fef 100644 --- a/docs/sources/trackers/java-tracker/tracking-events/index.md +++ b/docs/sources/trackers/java-tracker/tracking-events/index.md @@ -18,7 +18,7 @@ The Java tracker makes it easy to track different kinds of data. We provide a ra Every tracked event payload has a unique `event_id` UUID string. Other ubiquitous properties include the `name_tracker` (`trackerNamespace`) and `app_id` (`appId`) set when the `Tracker` was initialized. From version 0.12 onwards, `Tracker.track()` returns the payload's `eventId`. -Snowplow events have a defined structure and [protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md) that is identical regardless of the tracker used. A minimal payload - the raw event - is sent from the tracker to your collector. The raw event is [enriched](/docs/pipeline/enrichments/index.md) as it passes through your pipeline. By the time the event arrives in your data storage, depending which [enrichments](/docs/pipeline/enrichments/available-enrichments/index.md) you have enabled, it will have gained different kinds of metadata, and have many more fields than it started with. The default Java tracker event fields are shown [here](/docs/sources/trackers/java-tracker/what-do-java-tracker-events-look-like/index.md). +Snowplow events have a defined structure and [protocol](/docs/events/index.md) that is identical regardless of the tracker used. A minimal payload - the raw event - is sent from the tracker to your collector. The raw event is [enriched](/docs/pipeline/enrichments/index.md) as it passes through your pipeline. By the time the event arrives in your data storage, depending which [enrichments](/docs/pipeline/enrichments/available-enrichments/index.md) you have enabled, it will have gained different kinds of metadata, and have many more fields than it started with. The default Java tracker event fields are shown [here](/docs/sources/trackers/java-tracker/what-do-java-tracker-events-look-like/index.md). The [Java tracker Github repository](https://github.com/snowplow/snowplow-java-tracker) includes a mini demo, "simple-console". The demo sends one event of each type to your event collector. diff --git a/docs/sources/trackers/javascript-trackers/node-js-tracker/configuration/index.md b/docs/sources/trackers/javascript-trackers/node-js-tracker/configuration/index.md index 5f20613dd9..3da0894c31 100644 --- a/docs/sources/trackers/javascript-trackers/node-js-tracker/configuration/index.md +++ b/docs/sources/trackers/javascript-trackers/node-js-tracker/configuration/index.md @@ -40,7 +40,7 @@ t.setPlatform('mob'); If the platform is not set manually, it defaults to `'srv'` (for server). -For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters). +For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md#application-parameters). ### Set user ID with `setUserId()` diff --git a/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-0-3-0/configuration/index.md b/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-0-3-0/configuration/index.md index c6870c625a..6b41f25be3 100644 --- a/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-0-3-0/configuration/index.md +++ b/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-0-3-0/configuration/index.md @@ -34,7 +34,7 @@ t.setPlatform("mob"); If the platform is not set manually, it defaults to `'srv'` (for server). -For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters). +For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md#application-parameters). ### Set user ID with `setUserId()` diff --git a/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-0-4-0/configuration/index.md b/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-0-4-0/configuration/index.md index 532d77a118..8214627187 100644 --- a/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-0-4-0/configuration/index.md +++ b/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-0-4-0/configuration/index.md @@ -40,7 +40,7 @@ t.setPlatform("mob"); If the platform is not set manually, it defaults to `'srv'` (for server). -For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters). +For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md#application-parameters). ### Set user ID with `setUserId()` diff --git a/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-v3/configuration/index.md b/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-v3/configuration/index.md index 7b49b65b5e..ebefc6f47a 100644 --- a/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-v3/configuration/index.md +++ b/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-v3/configuration/index.md @@ -40,7 +40,7 @@ t.setPlatform('mob'); If the platform is not set manually, it defaults to `'srv'` (for server). -For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters). +For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md#application-parameters). ### Set user ID with `setUserId()` diff --git a/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-v3/initialization/index.md b/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-v3/initialization/index.md index 8f55dbea0b..0af347da03 100644 --- a/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-v3/initialization/index.md +++ b/docs/sources/trackers/javascript-trackers/node-js-tracker/previous-versions/node-js-tracker-v3/initialization/index.md @@ -93,7 +93,7 @@ Emitters must conform to an [`Emitter` interface](https://github.com/snowplow/sn interface Emitter { flush: () => void; input: (payload: PayloadDictionary) => void; - /** Set if the requests from the emitter should be anonymized. Read more about anonymization used at https://docs.snowplow.io/docs/sources/trackers/snowplow-tracker-protocol/going-deeper/http-headers/. Available from 3.21.0 onwards */ + /** Set if the requests from the emitter should be anonymized. Read more about anonymization used at https://docs.snowplow.io/docs/events/going-deeper/http-headers/. Available from 3.21.0 onwards */ setAnonymization?: (shouldAnonymize: boolean) => void; } ``` diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/browsers/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/browsers/index.md index dc4794b966..b1db56d653 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/browsers/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/browsers/index.md @@ -1,5 +1,5 @@ --- -title: "Browser support" +title: "Browser entity" date: "2021-04-07" sidebar_position: 2950 --- @@ -14,9 +14,9 @@ import ReleaseBadge from '@site/docs/reusable/javascript-tracker-release-badge-v The Snowplow web tracker supports tracking in all modern browsers, including new browser features such as [Privacy Sandbox](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/privacy-sandbox/index.md) and [Client Hints](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/client-hints/index.md). -## Browser context entity +## Browser entity -Add a context entity to every tracked event that records information about the user's browser. Configure it using the `"contexts"` object within the [tracker configuration object](/docs/sources/trackers/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md). +Add an entity to every tracked event that records information about the user's browser. Configure it using the `"contexts"` object within the [tracker configuration object](/docs/sources/trackers/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md).
Browser entity properties @@ -40,118 +40,6 @@ The [browser](https://github.com/snowplow/iglu-central/tree/master/schemas/com. | `tabId` | A UUID identifier for the client browser tab the event is sent from. | No | :::note -Please note that the browser context entity is only available since version 3.9 of the tracker. +Please note that the browser entity is only available since version 3.9 of the tracker. :::
- -## ITP mitigation - -As of Safari 16.4 released in April 2023, Safari sets the [lifetime of server-set first-party cookies](https://webkit.org/tracking-prevention/#cname-and-third-party-ip-address-cloaking-defense) to a maximum of 7 days in the following cases: - -1. The server setting the cookie is behind a CNAME that resolves (at any point) to a host that is third-party to the website the user is currently browsing. -2. The server setting the cookie is set with A/AAAA records that resolve to an IP address (IP4 or IP6) where the first half of the address does not match the first half of the IP address for the server on the website the user is currently browsing. (e.g. 203.52.1.2 and 203.52.56.22 are okay, 201.55.1.2 is not). - -This greatly limits the effectiveness of tracking a customer journey where users are not regularly returning to your website. Without a strong understanding of your customers, downstream use cases including marketing attribution, product analytics and personalized recommendations are difficult to achieve. - -**The ID service can help enhance the confidence in persistent browser identifiers that Snowplow tracking provides and specifically for this guide, the `network_userid`.** - -### What is an ID service ? - -An _ID service_, as we chose to call it, is a process that allows for generating a unique browser identifier and enhancing the Snowplow tracking capabilities in environments where the Intelligent Tracking Prevention (ITP) feature is enabled such as on iOS browsers (Safari, Chrome, Firefox) and desktop Safari. - -### Developing and deploying an ID service - -An ID service is code that needs to be deployed on and executed from the same IP space that serves the main web document of your application. This is probably the web application system or the CDN in front of the application. - -This code has minimal functionality and based on our experience can either be: - -- An **API endpoint** that is part of the main web application. -- **A function running in an edge worker.** Almost all modern CDNs allow the addition of ‘middleware’ code which runs on requests at edge nodes in front of the client’s application domain. -- **A custom middleware based on the customer’s framework**. E.g. ExpressJS middleware, Next.js middleware, Play custom action etc. which can run on every document request. -- **A low-footprint application with a single endpoint**. A Go web server or something along these lines. - -#### Developing the ID service code - -The responsibilities of this service are: -1. Create a unique identifier (UUID v4) for this browser, set it in a cookie and return it in a `Set-Cookie` response header on a domain accessible by the service at all times. -2. Increase the expiry for the cookie used as the network_userid identifier (by default, a cookie named sp, configured via collector.config.name) which should have the same value as the first cookie. - -_The new unique identifier cookie for sake of simplicity in this document will have the name `spIdService`._ - -#### ID service business logic - -The ID service code should include the following logic: - -- If the ID service new identifier cookie already exists on the request, then it should re-set the cookies with the same values and updated expiration for both the `spIdService` and `sp` cookies. -- If `spIdService` does not exist, but the collector's `sp` cookie does exist, then the it should set `spIdService value = sp cookie value`. _This will make sure we keep old identifiers in place and not lose any data._ -- 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 - -Below we showcase a couple of code samples for ID service API endpoints: - - - - -```ts reference -https://github.com/snowplow-industry-solutions/id-service-examples/blob/main/examples/typescript/Next.js/api-route.ts -``` - - - - -```php reference -https://github.com/snowplow-industry-solutions/id-service-examples/blob/main/examples/php/wordpress/api-route.php -``` - - - - - -### Using the ID service on the Snowplow browser tracker - -When the ID service has been deployed on a system with the same resolved IP as the main document, the tracker can then be configured to orchestrate the required ID service API calls. - -This process is opt-in by using the `idService` option during tracker initialization: - - - - -```tsx -window.snowplow("newTracker", "sp", "{{collector_url_here}}", { - /* ...Rest of the tracker options */ - idService: "/id-service-endpoint" -}); -``` - - - - -```tsx -newTracker('sp1', 'c.customer.com', { - idService: "/id-service-endpoint", - /* ...Rest of the tracker options */ - }); -``` - - - - -When the tracker detects this option it will send an HTTP request during initialization on this endpoint to have the service set the required identifiers before sending any event. - -```mermaid -sequenceDiagram - autonumber - participant Service as ID Service Endpoint - participant Tracking as Snowplow Tracking Code - participant Collector as Snowplow Collector - Tracking->>Service: Request an ID - note over Service: ID Service code - Service->>Tracking: OK response - note over Tracking,Service: Set-Cookie: sp=...
Set-Cookie: spIdService=... - loop Normal flow - Tracking->>Collector: Event Tracking - note over Tracking,Collector: Cookie: sp=...#59; spIdService=... - end -``` diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/index.md index a1ae707b5f..b3b05a6189 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/cookies-and-local-storage/index.md @@ -69,7 +69,7 @@ Local storage will only be used if `stateStorageStrategy` is set to `localSto ## Mapping values to tracker protocol -The values stored in the cookies listed above are mapped into the [tracker protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md) when events are sent to a Snowplow Collector. +The values stored in the cookies listed above are mapped into the [tracker protocol](/docs/events/index.md) when events are sent to a Snowplow Collector. The below table shows which parameters the cookie values map to: diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/custom-tracking-using-schemas/global-context/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/custom-tracking-using-schemas/global-context/index.md index 6af1bc2175..bc283e195e 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/custom-tracking-using-schemas/global-context/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/custom-tracking-using-schemas/global-context/index.md @@ -118,7 +118,7 @@ This argument is a string taken from the event payload field, `e`. | Custom structured event | se | | Custom self describing event | ue | -Further information about the event payload can be found in the [tracker protocol documentation](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +Further information about the event payload can be found in the [tracker protocol documentation](/docs/events/index.md). #### `eventSchema` diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/plugins/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/plugins/index.md index 2c1dac5a03..76426af7a4 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/plugins/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/plugins/index.md @@ -30,6 +30,7 @@ If you are using the JavaScript tracker with the full `sp.js` and your plugin is | [Ecommerce (Snowplow)](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ecommerce/index.md) | Events and entities | Manual | ✅ | ❌ | `browser-plugin-snowplow-ecommerce` | | [Ecommerce (Enhanced)](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ecommerce/enhanced/index.md) | Events | Manual | ❌ | ❌ | `browser-plugin-enhanced-ecommerce` | | [Errors](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/errors/index.md) | Events | Manual and automatic | ✅ | ❌ | `browser-plugin-error-tracking` | +| [Element visibility](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/element-tracking/index.md) | Events | Automatic | ❌ | ❌ | `browser-plugin-element-tracking` | | [Event Specifications](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/event-specifications/index.md) | Entities | Automatic | ❌ | ❌ | `browser-plugin-event-specifications` | | [Forms](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/form-tracking/index.md) | Events | Automatic | ✅ | ❌ | `browser-plugin-form-tracking` | | [GA cookies](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ga-cookies/index.md) | Entities | Automatic | ✅ | ❌ | `browser-plugin-ga-cookies` | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/ad-tracking/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/ad-tracking/index.md index 4985ca4797..b04fef9601 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/ad-tracking/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/ad-tracking/index.md @@ -22,15 +22,15 @@ import ReleaseBadge from '@site/docs/reusable/javascript-tracker-release-badge-v import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { AdTrackingPlugin, trackAdClick } from '@snowplow/browser-plugin-ad-tracking'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ AdTrackingPlugin() ], }); ``` ### Functions -
trackAdImpressionDocumentation
trackAdClickDocumentation
trackAdConversionDocumentation
+
trackAdImpressionDocumentation
trackAdClickDocumentation
trackAdConversionDocumentation
### Context diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/consent/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/consent/index.md index 0693460310..f56759e75f 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/consent/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/consent/index.md @@ -22,20 +22,20 @@ import ReleaseBadge from '@site/docs/reusable/javascript-tracker-release-badge-v import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { ConsentPlugin } from '@snowplow/browser-plugin-consent'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ ConsentPlugin() ], }); ``` ### Functions -
enableGdprContextDocumentation
trackConsentGrantedDocumentation
trackConsentWithdrawnDocumentation
+
enableGdprContextDocumentation
trackConsentGrantedDocumentation
trackConsentWithdrawnDocumentation
### Context Adding this plugin will automatically capture the following context: -| Context | Example | -|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------| +| Context | Example | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | | [iglu:com.snowplowanalytics.snowplow/consent_document/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/consent_document/jsonschema/1-0-0) | ![](images/Screenshot-2021-03-28-at-20.04.43.png) | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/ecommerce/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/ecommerce/index.md index d34e336e0c..dac9139d6f 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/ecommerce/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/ecommerce/index.md @@ -22,15 +22,15 @@ import ReleaseBadge from '@site/docs/reusable/javascript-tracker-release-badge-v import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { EcommercePlugin, addTrans, addItem, trackTrans } from '@snowplow/browser-plugin-ecommerce'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ EcommercePlugin() ], }); ``` ### Functions -
addTransDocumentation
addItemDocumentation
trackTransDocumentation
trackAddToCartDocumentation
trackRemoveFromCartDocumentation
+
addTransDocumentation
addItemDocumentation
trackTransDocumentation
trackAddToCartDocumentation
trackRemoveFromCartDocumentation
### Context diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/enhanced-ecommerce/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/enhanced-ecommerce/index.md index ed2bd7f7cf..d77fce3042 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/enhanced-ecommerce/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/enhanced-ecommerce/index.md @@ -22,15 +22,15 @@ import ReleaseBadge from '@site/docs/reusable/javascript-tracker-release-badge-v import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { EnhancedEcommercePlugin, trackEnhancedEcommerceAction } from '@snowplow/browser-plugin-enhanced-ecommerce'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ EnhancedEcommercePlugin() ], }); ``` ### Functions -
trackEnhancedEcommerceActionDocumentation
addEnhancedEcommerceActionContextDocumentation
addEnhancedEcommerceImpressionContextDocumentation
addEnhancedEcommerceProductContextDocumentation
addEnhancedEcommercePromoContextDocumentation
+
trackEnhancedEcommerceActionDocumentation
addEnhancedEcommerceActionContextDocumentation
addEnhancedEcommerceImpressionContextDocumentation
addEnhancedEcommerceProductContextDocumentation
addEnhancedEcommercePromoContextDocumentation
### Context diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/error-tracking/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/error-tracking/index.md index d5304832e9..481325c1d5 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/error-tracking/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/error-tracking/index.md @@ -24,8 +24,8 @@ This tracker plugin provides two ways of tracking exceptions: manual tracking of import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { ErrorTrackingPlugin, enableErrorTracking } from '@snowplow/browser-plugin-error-tracking'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ ErrorTrackingPlugin() ], }); @@ -34,7 +34,7 @@ enableErrorTracking(); ### Functions -
trackErrorDocumentation
enableErrorTrackingDocumentation
+
trackErrorDocumentation
enableErrorTrackingDocumentation
### Context diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/form-tracking/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/form-tracking/index.md index 54c71d6397..d6bb5f3b1a 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/form-tracking/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/form-tracking/index.md @@ -26,8 +26,8 @@ Snowplow automatic form tracking detects three event types: `change_form`, `subm import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { FormTrackingPlugin, enableFormTracking } from '@snowplow/browser-plugin-form-tracking'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ FormTrackingPlugin() ], }); @@ -36,7 +36,7 @@ enableFormTracking(); ### Functions -
enableFormTrackingDocumentation
+
enableFormTrackingDocumentation
### Context diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/geolocation/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/geolocation/index.md index 73dbf6aa42..c0e942e65a 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/geolocation/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/geolocation/index.md @@ -34,7 +34,7 @@ enableGeolocationContext(); ### Functions - +
enableGeolocationContext @@ -49,6 +49,6 @@ enableGeolocationContext(); Adding this plugin will automatically capture the following context: -| Context | Example | -|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------| +| Context | Example | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | | [iglu:com.snowplowanalytics.snowplow/geolocation_context/jsonschema/1-1-0](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/geolocation_context/jsonschema/1-1-0) | ![](images/Screenshot-2021-03-30-at-22.25.13.png) | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/link-click-tracking/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/link-click-tracking/index.md index 397d94d8a1..ad1e79fec7 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/link-click-tracking/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/link-click-tracking/index.md @@ -24,8 +24,8 @@ Link click tracking is enabled using the `enableLinkClickTracking` method. Use import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { LinkClickTrackingPlugin, enableLinkClickTracking } from '@snowplow/browser-plugin-link-click-tracking'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ LinkClickTrackingPlugin() ], }); @@ -34,7 +34,7 @@ enableLinkClickTracking(); ### Functions -
enableLinkClickTrackingDocumentation
refreshLinkClickTrackingDocumentation
trackLinkClickDocumentation
+
enableLinkClickTrackingDocumentation
refreshLinkClickTrackingDocumentation
trackLinkClickDocumentation
### Context diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/site-tracking/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/site-tracking/index.md index a92bab7e32..947d71ad69 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/site-tracking/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/plugins/site-tracking/index.md @@ -22,15 +22,15 @@ import ReleaseBadge from '@site/docs/reusable/javascript-tracker-release-badge-v import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { SiteTrackingPlugin, trackSiteSearch } from '@snowplow/browser-plugin-site-tracking'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ SiteTrackingPlugin() ], }); ``` ### Functions -
trackSocialInteractionDocumentation
trackSiteSearchDocumentation
trackTimingDocumentation
+
trackSocialInteractionDocumentation
trackSiteSearchDocumentation
trackTimingDocumentation
### Context diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/tracker-setup/initialization-options/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/tracker-setup/initialization-options/index.md index 885de59790..f1d7afdf9a 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/tracker-setup/initialization-options/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/tracker-setup/initialization-options/index.md @@ -79,7 +79,7 @@ Set the application ID using the `appId` field of the configuration object. Th #### Setting the platform -Set the application platform using the `platform` field of the configuration object. This will be attached to every event the tracker fires. Its default value is “web”. For a list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters). +Set the application platform using the `platform` field of the configuration object. This will be attached to every event the tracker fires. Its default value is “web”. For a list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md#application-parameters). #### Configuring the cookie domain diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/tracking-events/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/tracking-events/index.md index 61aec11a54..66b956e1fd 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/tracking-events/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/browser-tracker-v3-reference/tracking-events/index.md @@ -548,7 +548,7 @@ This argument is a string taken from the event payload field, `e`. | Custom structured event | se | | Custom self describing event | ue | -Further information about the event payload can be found in the [tracker protocol documentation](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +Further information about the event payload can be found in the [tracker protocol documentation](/docs/events/index.md). ##### `eventSchema` diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/javascript-tracker-v2/tracker-setup/initializing-a-tracker-2/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/javascript-tracker-v2/tracker-setup/initializing-a-tracker-2/index.md index be1c5a1801..eff1584f5c 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/javascript-tracker-v2/tracker-setup/initializing-a-tracker-2/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/javascript-tracker-v2/tracker-setup/initializing-a-tracker-2/index.md @@ -113,7 +113,7 @@ Set the application ID using the `appId` field of the configuration object. Th #### Setting the platform -Set the application platform using the `platform` field of the configuration object. This will be attached to every event the tracker fires. Its default value is “web”. For a list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters). +Set the application platform using the `platform` field of the configuration object. This will be attached to every event the tracker fires. Its default value is “web”. For a list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md#application-parameters). #### Configuring the cookie domain @@ -473,7 +473,7 @@ When initialising the tracker, you can specify an array of features to skip. Full list of features: - `res` - Screen Resolution -- `cd` - Screen Colour Depth +- `cd` - Screen Color Depth - `cookie` - Cookie support (if cookies enabled in tracker initialization) - `pdf` - PDF MimeType Support (application/pdf) - `qt` - Quicktime Video MimeType Support (video/quicktime) diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/javascript-tracker-v2/tracking-specific-events/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/javascript-tracker-v2/tracking-specific-events/index.md index b862154f4f..f098ac4d1c 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/javascript-tracker-v2/tracking-specific-events/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/javascript-tracker-v2/tracking-specific-events/index.md @@ -661,7 +661,7 @@ This argument is a string taken from the event payload field, `e`. | Custom structured event | se | | Custom self describing event | ue | -Further information about the event payload can be found in the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +Further information about the event payload can be found in the [Snowplow Tracker Protocol](/docs/events/index.md). ##### `eventSchema` diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/cookies-and-local-storage/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/cookies-and-local-storage/index.md index a74092df58..7a947cb50b 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/cookies-and-local-storage/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/cookies-and-local-storage/index.md @@ -69,7 +69,7 @@ Local storage will only be used if `stateStorageStrategy` is set to `localSto ## Mapping values to tracker protocol -The values stored in the cookies listed above are mapped into the [tracker protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md) when events are sent to a Snowplow Collector. +The values stored in the cookies listed above are mapped into the [tracker protocol](/docs/events/index.md) when events are sent to a Snowplow Collector. The below table shows which parameters the cookie values map to: diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/custom-tracking-using-schemas/global-context/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/custom-tracking-using-schemas/global-context/index.md index e09dfe1760..a22ed04f26 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/custom-tracking-using-schemas/global-context/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/custom-tracking-using-schemas/global-context/index.md @@ -118,7 +118,7 @@ This argument is a string taken from the event payload field, `e`. | Custom structured event | se | | Custom self describing event | ue | -Further information about the event payload can be found in the [tracker protocol documentation](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +Further information about the event payload can be found in the [tracker protocol documentation](/docs/events/index.md). #### `eventSchema` diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/plugins/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/plugins/index.md index 8542b56e1a..f9a0d0712d 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/plugins/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/plugins/index.md @@ -20,36 +20,36 @@ The following table lists the Snowplow plugins (alphabetical order), what kinds If you are using the JavaScript tracker with the full `sp.js` and your plugin is included, no further installation or initialization is required. You can use it straight away. -| Plugin | Creates | Tracked | `sp.js` | `sp.lite.js` | Package name | -|-------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|----------------------|---------|--------------|------------------------------------------------| -| [Ads](../tracking-events/ads/index.md) | Events | Manual | ✅ | ❌ | `browser-plugin-ad-tracking` | -| [Button click](../tracking-events/button-click/index.md) | Events | Automatic | ❌ | ❌ | `browser-plugin-button-click-tracking` | -| [Client Hints](../tracking-events/client-hints/index.md) | Entities | Automatic | ✅ | ❌ | `browser-plugin-client-hints` | -| [Consent (Enhanced)](../tracking-events/consent-gdpr/index.md) | Events and entities | Manual | ❌ | ❌ | `browser-plugin-enhanced-consent` | -| [Consent (original)](../tracking-events/consent-gdpr/original/index.md) | Events and entities | Manual and automatic | ✅ | ❌ | `browser-plugin-consent` | -| [Debugger](../testing-debugging/index.md) | Other | n/a | ❌ | ❌ | `browser-plugin-debugger` | -| [Ecommerce (Snowplow)](../tracking-events/ecommerce/index.md) | Events and entities | Manual | ❌ | ❌ | `browser-plugin-snowplow-ecommerce` | -| [Ecommerce (Enhanced)](../tracking-events/ecommerce/enhanced/index.md) | Events | Manual | ✅ | ❌ | `browser-plugin-enhanced-ecommerce` | -| [Ecommerce (original)](../tracking-events/ecommerce/original/index.md) | Events | Manual | ✅ | ❌ | `browser-plugin-ecommerce` | -| [Errors](../tracking-events/errors/index.md) | Events | Manual and automatic | ✅ | ❌ | `browser-plugin-error-tracking` | -| [Event Specifications](../tracking-events/event-specifications/index.md) | Entities | Automatic | ❌ | ❌ | `browser-plugin-event-specifications` | -| [Forms](../tracking-events/form-tracking/index.md) | Events | Automatic | ✅ | ❌ | `browser-plugin-form-tracking` | -| [GA cookies](../tracking-events/ga-cookies/index.md) | Entities | Automatic | ✅ | ❌ | `browser-plugin-ga-cookies` | -| [Geolocation](../tracking-events/timezone-geolocation/index.md) | Entities | Automatic | ✅ | ❌ | `browser-plugin-geolocation` | -| [Kantar Focal Meter](../tracking-events/focalmeter/index.md) | Other | n/a | ❌ | ❌ | `browser-plugin-focalmeter@focalmeter_plugin` | -| [Link click](../tracking-events/link-click/index.md) | Events | Automatic | ✅ | ❌ | `browser-plugin-link-click-tracking` | -| [Media (Snowplow)](../tracking-events/media/index.md) | Events and entities | Manual | ❌ | ❌ | `browser-plugin-media` | -| [Media (HTML)](../tracking-events/media/html5/index.md) | Events and entities | Automatic | ❌ | ❌ | `browser-plugin-media-tracking` | -| [Media (Vimeo)](../tracking-events/media/vimeo/index.md) | Events and entities | Automatic | ❌ | ❌ | `browser-plugin-vimeo-tracking` | -| [Media (Youtube)](../tracking-events/media/youtube/index.md) | Events and entities | Automatic | ❌ | ❌ | `browser-plugin-youtube-tracking` | -| [Optimizely X](../tracking-events/optimizely/index.md) | Entities | Automatic | ✅ | ❌ | `browser-plugin-optimizely-x` | -| [Performance navigation timing](../tracking-events/timings/index.md) | Entities | Automatic | ❌ | ❌ | `browser-plugin-performance-navigation-timing` | -| [Performance timing (original)](../tracking-events/timings/index.md) | Entities | Automatic | ✅ | ❌ | `browser-plugin-performance-timing` | -| [Privacy Sandbox](../tracking-events/privacy-sandbox/index.md) | Entities | Automatic | ❌ | ❌ | `browser-plugin-privacy-sandbox` | -| Site* | Events | Manual | ✅ | ❌ | `browser-plugin-site-tracking` | -| [Timezone](../tracking-events/timezone-geolocation/index.md) | Other | Automatic | ❌ | ❌ | `browser-plugin-timezone` | -| [Web vitals](../tracking-events/web-vitals/index.md) | Events | Automatic | ❌ | ❌ | `browser-plugin-web-vitals` | -| ~~[Browser features](#browser-features)~~ deprecated | Events | Automatic | ❌ | ❌ | `browser-plugin-browser-features` | +| Plugin | Creates | Tracked | `sp.js` | `sp.lite.js` | Package name | +| ------------------------------------------------------------------------ | ------------------- | -------------------- | ------- | ------------ | ---------------------------------------------- | +| [Ads](../tracking-events/ads/index.md) | Events | Manual | ✅ | ❌ | `browser-plugin-ad-tracking` | +| [Button click](../tracking-events/button-click/index.md) | Events | Automatic | ❌ | ❌ | `browser-plugin-button-click-tracking` | +| [Client Hints](../tracking-events/client-hints/index.md) | Entities | Automatic | ✅ | ❌ | `browser-plugin-client-hints` | +| [Consent (Enhanced)](../tracking-events/consent-gdpr/index.md) | Events and entities | Manual | ❌ | ❌ | `browser-plugin-enhanced-consent` | +| [Consent (original)](../tracking-events/consent-gdpr/original/index.md) | Events and entities | Manual and automatic | ✅ | ❌ | `browser-plugin-consent` | +| [Debugger](../testing-debugging/index.md) | Other | n/a | ❌ | ❌ | `browser-plugin-debugger` | +| [Ecommerce (Snowplow)](../tracking-events/ecommerce/index.md) | Events and entities | Manual | ❌ | ❌ | `browser-plugin-snowplow-ecommerce` | +| [Ecommerce (Enhanced)](../tracking-events/ecommerce/enhanced/index.md) | Events | Manual | ✅ | ❌ | `browser-plugin-enhanced-ecommerce` | +| [Ecommerce (original)](../tracking-events/ecommerce/original/index.md) | Events | Manual | ✅ | ❌ | `browser-plugin-ecommerce` | +| [Errors](../tracking-events/errors/index.md) | Events | Manual and automatic | ✅ | ❌ | `browser-plugin-error-tracking` | +| [Event Specifications](../tracking-events/event-specifications/index.md) | Entities | Automatic | ❌ | ❌ | `browser-plugin-event-specifications` | +| [Forms](../tracking-events/form-tracking/index.md) | Events | Automatic | ✅ | ❌ | `browser-plugin-form-tracking` | +| [GA cookies](../tracking-events/ga-cookies/index.md) | Entities | Automatic | ✅ | ❌ | `browser-plugin-ga-cookies` | +| [Geolocation](../tracking-events/timezone-geolocation/index.md) | Entities | Automatic | ✅ | ❌ | `browser-plugin-geolocation` | +| [Kantar Focal Meter](../tracking-events/focalmeter/index.md) | Other | n/a | ❌ | ❌ | `browser-plugin-focalmeter@focalmeter_plugin` | +| [Link click](../tracking-events/link-click/index.md) | Events | Automatic | ✅ | ❌ | `browser-plugin-link-click-tracking` | +| [Media (Snowplow)](../tracking-events/media/index.md) | Events and entities | Manual | ❌ | ❌ | `browser-plugin-media` | +| [Media (HTML)](../tracking-events/media/html5/index.md) | Events and entities | Automatic | ❌ | ❌ | `browser-plugin-media-tracking` | +| [Media (Vimeo)](../tracking-events/media/vimeo/index.md) | Events and entities | Automatic | ❌ | ❌ | `browser-plugin-vimeo-tracking` | +| [Media (Youtube)](../tracking-events/media/youtube/index.md) | Events and entities | Automatic | ❌ | ❌ | `browser-plugin-youtube-tracking` | +| [Optimizely X](../tracking-events/optimizely/index.md) | Entities | Automatic | ✅ | ❌ | `browser-plugin-optimizely-x` | +| [Performance navigation timing](../tracking-events/timings/index.md) | Entities | Automatic | ❌ | ❌ | `browser-plugin-performance-navigation-timing` | +| [Performance timing (original)](../tracking-events/timings/index.md) | Entities | Automatic | ✅ | ❌ | `browser-plugin-performance-timing` | +| [Privacy Sandbox](../tracking-events/privacy-sandbox/index.md) | Entities | Automatic | ❌ | ❌ | `browser-plugin-privacy-sandbox` | +| Site* | Events | Manual | ✅ | ❌ | `browser-plugin-site-tracking` | +| [Timezone](../tracking-events/timezone-geolocation/index.md) | Other | Automatic | ❌ | ❌ | `browser-plugin-timezone` | +| [Web vitals](../tracking-events/web-vitals/index.md) | Events | Automatic | ❌ | ❌ | `browser-plugin-web-vitals` | +| ~~[Browser features](#browser-features)~~ deprecated | Events | Automatic | ❌ | ❌ | `browser-plugin-browser-features` | *The site tracking plugin provides events for [site search](../tracking-events/site-search/index.md), [social media interactions](../tracking-events/social-media/index.md), and [timing](../tracking-events/timings/generic/index.md). @@ -67,13 +67,13 @@ You can find the plugins code [here](https://github.com/snowplow/snowplow-javasc | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ❌ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/testing-debugging/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/testing-debugging/index.md index d9373e5f20..f0430efad7 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/testing-debugging/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/testing-debugging/index.md @@ -49,7 +49,7 @@ An example of the output from this plugin: **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ads/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ads/index.md index f5ad52997e..49065308b6 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ads/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ads/index.md @@ -24,13 +24,13 @@ Snowplow ad events must be **manually tracked**. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. @@ -70,7 +70,7 @@ The ad tracking plugin includes three event types: ad impression, ad click, and Ad impression tracking is accomplished using the `trackAdImpression` method. Here are the arguments it accepts: | **Name** | **Required?** | **Description** | **Type** | -|----------------|---------------|----------------------------------------------------------------------|----------| +| -------------- | ------------- | -------------------------------------------------------------------- | -------- | | `impressionId` | No | Identifier for the particular impression instance | string | | `costModel` | No | The cost model for the campaign: 'cpc', 'cpm', or 'cpa' | string | | `cost` | No | Ad cost | number | @@ -130,7 +130,7 @@ Ad impression events are implemented as Snowplow self describing events. [Here] Ad click tracking is accomplished using the `trackAdClick` method. Here are the arguments it accepts: | **Name** | **Required?** | **Description** | **Type** | -|----------------|---------------|----------------------------------------------------------------------|----------| +| -------------- | ------------- | -------------------------------------------------------------------- | -------- | | `targetUrl` | Yes | The destination URL | string | | `clickId` | No | Identifier for the particular click instance | string | | `costModel` | No | The cost model for the campaign: 'cpc', 'cpm', or 'cpa' | string | @@ -188,7 +188,7 @@ Ad click events are implemented as Snowplow self describing events.[Here](https: Use the `trackAdConversion` method to track ad conversions. Here are the arguments it accepts: | **Name** | **Required?** | **Description** | **Type** | -|----------------|---------------|----------------------------------------------------------------------|----------| +| -------------- | ------------- | -------------------------------------------------------------------- | -------- | | `conversionId` | No | Identifier for the particular conversion instance | string | | `costModel` | No | The cost model for the campaign: 'cpc', 'cpm', or 'cpa' | string | | `cost` | No | Ad cost | number | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/button-click/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/button-click/index.md index 813fda6fd3..3a0ad67a49 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/button-click/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/button-click/index.md @@ -24,7 +24,7 @@ Button click events are **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ❌ | | `sp.lite.js` | ❌ | @@ -217,7 +217,7 @@ enableButtonClickTracking({ The plugin will track the following data (if present on the element): | Field | Description | Type | Required? | -|-----------|-----------------------------------------------------|------------|-----------| +| --------- | --------------------------------------------------- | ---------- | --------- | | `label` | The text on the button, or a user-provided override | `string` | Yes | | `id` | The ID of the button | `string` | No | | `classes` | The classes of the button | `string[]` | No | @@ -256,7 +256,7 @@ Suppose we have the following button on our page: ```html ``` @@ -291,7 +291,7 @@ Suppose we have the following button on our page: ```html ``` diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/client-hints/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/client-hints/index.md index 28769c2b40..ea2187e27e 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/client-hints/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/client-hints/index.md @@ -31,18 +31,18 @@ The Client Hints context entity is **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-client-hints@3/dist/index.umd.min.js", ["snowplowClientHints", "ClientHintsPlugin"] ); @@ -59,9 +59,9 @@ window.snowplow('addPlugin', import { newTracker } from '@snowplow/browser-tracker'; import { ClientHintsPlugin } from '@snowplow/browser-plugin-client-hints'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', - plugins: [ ClientHintsPlugin() ], +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', + plugins: [ ClientHintsPlugin() ], // Use ClientHintsPlugin(true) to capture high entropy values }); ``` diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/consent-gdpr/original/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/consent-gdpr/original/index.md index 62baf56272..3da4cf4e41 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/consent-gdpr/original/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/consent-gdpr/original/index.md @@ -23,13 +23,13 @@ Original consent events must be **manually tracked**. The GDPR context entity wi | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. @@ -67,7 +67,7 @@ newTracker('sp1', '{{collector_url}}', { Use the `trackConsentGranted` method to track a user opting into data collection. A consent document context will be attached to the event if at least the `id` and `version` arguments are supplied. The method arguments are: | **Name** | **Description** | **Required?** | **Type** | -|---------------|-----------------------------------------------------------|---------------|------------------| +| ------------- | --------------------------------------------------------- | ------------- | ---------------- | | `id` | Identifier for the document granting consent | Yes | String | | `version` | Version of the document granting consent | Yes | String | | `name` | Name of the document granting consent | No | String | @@ -116,7 +116,7 @@ Use the `trackConsentWithdrawn` method to track a user withdrawing consent for The method arguments are: | **Name** | **Description** | **Required?** | **Type** | -|---------------|---------------------------------------------------|---------------|------------------| +| ------------- | ------------------------------------------------- | ------------- | ---------------- | | `all` | Specifies whether all consent should be withdrawn | No | Boolean | | `id` | Identifier for the document withdrawing consent | No | String | | `version` | Version of the document withdrawing consent | No | string | @@ -166,7 +166,7 @@ The JSON schema for a consent document can be found [here](https://github.com/sn The fields of a consent document are: | **Name** | **Description** | **Required?** | **Type** | -|---------------|-----------------------------|---------------|----------| +| ------------- | --------------------------- | ------------- | -------- | | `id` | Identifier for the document | Yes | String | | `version` | Version of the document | Yes | String | | `name` | Name of the document | No | String | @@ -253,7 +253,7 @@ Attach a context entity with the GDPR basis for processing and the details of a It takes the following arguments: | **Name** | **Description** | **Required?** | **Type** | -|-----------------------|-----------------------------|---------------|-------------| +| --------------------- | --------------------------- | ------------- | ----------- | | `basisForProcessing` | GDPR Basis for processing | Yes | Enum String | | `documentId` | ID of a GDPR basis document | No | String | | `documentVersion` | Version of the document | No | String | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ecommerce/enhanced/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ecommerce/enhanced/index.md index 3ddaa6d562..77751153ca 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ecommerce/enhanced/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ecommerce/enhanced/index.md @@ -24,13 +24,13 @@ Enhanced ecommerce events must be **manually tracked**. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. @@ -68,7 +68,7 @@ The enhanced ecommerce plugin is based around the `EnhancedEcommerceAction` even Use the `trackEnhancedEcommerceAction` method to track a GA Enhanced Ecommerce Action. When this function is called all of the added Ecommerce context entities are attached to this action and flushed from the tracker. | **Name** | **Required?** | **Type** | -|----------|---------------|----------| +| -------- | ------------- | -------- | | `action` | Yes | string | The allowed actions: @@ -124,7 +124,7 @@ The enhanced ecommerce context entities are specific to this plugin, and cannot Use the `addEnhancedEcommerceActionContext` method to add a GA Enhanced Ecommerce Action Context to the Tracker: | **Name** | **Required?** | **Type** | -|---------------|---------------|-------------------| +| ------------- | ------------- | ----------------- | | `id` | Yes | string | | `affiliation` | No | string | | `revenue` | No | number OR string | @@ -190,7 +190,7 @@ addEnhancedEcommerceActionContext({ Use the `addEnhancedEcommerceImpressionContext` method to add a GA Enhanced Ecommerce Impression Context to the Tracker: | **Name** | **Required?** | **Type** | -|------------|---------------|-------------------| +| ---------- | ------------- | ----------------- | | `id` | Yes | string | | `name` | No | string | | `list` | No | string | @@ -255,7 +255,7 @@ addEnhancedEcommerceImpressionContext({ Use the `addEnhancedEcommerceProductContext` method to add a GA Enhanced Ecommerce Product Field Context: | **Name** | **Required?** | **Type** | -|------------|---------------|-------------------| +| ---------- | ------------- | ----------------- | | `id` | Yes | string | | `name` | No | string | | `list` | No | string | @@ -320,7 +320,7 @@ addEnhancedEcommerceProductContext({ Use the `addEnhancedEcommercePromoContext` method to add a GA Enhanced Ecommerce Promotion Field Context: | **Name** | **Required?** | **Type** | -|------------|---------------|----------| +| ---------- | ------------- | -------- | | `id` | Yes | string | | `name` | No | string | | `creative` | No | string | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ecommerce/original/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ecommerce/original/index.md index d77f31f7ab..4844d31f39 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ecommerce/original/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ecommerce/original/index.md @@ -28,13 +28,13 @@ Original ecommerce events must be **manually tracked**. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. @@ -76,7 +76,7 @@ The transaction object must be created first, using `addTrans()`. Add items with The `addTrans` method creates a transaction object. It takes nine possible parameters, two of which are required: | **Parameter** | **Description** | **Required?** | **Example value** | -|---------------|------------------------------------------------------|---------------|-------------------| +| ------------- | ---------------------------------------------------- | ------------- | ----------------- | | `orderId` | Internal unique order id number for this transaction | Yes | '1234' | | `affiliation` | Partner or store affiliation | No | 'Womens Apparel' | | `total` | Total amount of the transaction | Yes | '19.99' | @@ -151,7 +151,7 @@ The `addItem` method is used to capture the details of each product item inclu There are six potential parameters that can be passed with each call, four of which are required: | **Parameter** | **Description** | **Required?** | **Example value** | -|---------------|----------------------------------------------------|-----------------------------------------------------|-------------------| +| ------------- | -------------------------------------------------- | --------------------------------------------------- | ----------------- | | `orderId` | Order ID of the transaction to associate with item | Yes | '1234' | | `sku` | Item's SKU code | Yes | 'pbz0001234' | | `name` | Product name | No, but advisable (to make interpreting SKU easier) | 'Black Tarot' | @@ -333,7 +333,7 @@ trackTrans(); These methods are also part of `@snowplow/browser-plugin-ecommerce` and let you track users adding and removing items from a cart on an ecommerce site. Their arguments are identical: | **Name** | **Required?** | **Description** | **Type** | -|-------------|---------------|----------------------------------------|----------| +| ----------- | ------------- | -------------------------------------- | -------- | | `sku` | Yes | Item SKU | string | | `name` | No | Item name | string | | `category` | No | Item category | string | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/errors/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/errors/index.md index 7b55901ce6..fd877a4b8e 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/errors/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/errors/index.md @@ -20,18 +20,18 @@ Error events can be **manually tracked** and/or **automatically tracked**. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-error-tracking@3/dist/index.umd.min.js", ["snowplowErrorTracking", "ErrorTrackingPlugin"] ); @@ -48,8 +48,8 @@ window.snowplow('addPlugin', import { newTracker } from '@snowplow/browser-tracker'; import { ErrorTrackingPlugin, enableErrorTracking } from '@snowplow/browser-plugin-error-tracking'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ ErrorTrackingPlugin() ], }); @@ -103,7 +103,7 @@ trackError({ | **Name** | **Required?** | **Description** | **Type** | -|------------|---------------|-------------------------------------|------------| +| ---------- | ------------- | ----------------------------------- | ---------- | | `message` | Yes | Error message | string | | `filename` | No | Filename or URL | string | | `lineno` | No | Line number of problem code chunk | number | @@ -183,7 +183,7 @@ enableErrorTracking({ | **Name** | **Required?** | **Description** | **Type** | -|----------------|---------------|---------------------------------|---------------------------------------------| +| -------------- | ------------- | ------------------------------- | ------------------------------------------- | | `filter` | No | Predicate to filter exceptions | `(ErrorEvent) => Boolean` | | `contextAdder` | No | Function to get dynamic context | `(ErrorEvent) => Array` | | context | No | Additional custom context | `Array` | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/form-tracking/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/form-tracking/index.md index 7ea8ed12e3..1b6e5ed426 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/form-tracking/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/form-tracking/index.md @@ -26,12 +26,12 @@ Form events are **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ga-cookies/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ga-cookies/index.md index a0e079c8a9..4335199f01 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ga-cookies/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/ga-cookies/index.md @@ -20,13 +20,13 @@ GA cookies information is **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. @@ -113,7 +113,7 @@ interface GACookiesPluginOptions { ``` | Name | Default | Description | -|------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ua | `true` | Send Universal Analytics specific cookie values. | | ga4 | `false` | Send Google Analytics 4 specific cookie values. | | ga4MeasurementId | `""` | Measurement id(s) to search the Google Analytics 4 session cookie. Can be a single measurement id as a string or an array of measurement id strings. The cookie has the form of `_ga_` where `` is the data stream container id and `` is the optional `cookie_prefix` option of the gtag.js tracker. | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/index.md index c0b1fcecfe..a1553fd2b4 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/index.md @@ -108,7 +108,7 @@ trackPageView({ -Every tracked event payload has a unique `event_id` UUID string set by the tracker, a set of timestamps, and other ubiquitous properties such as the `namespace`. You can find out more about how events and entities are structured [here](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +Every tracked event payload has a unique `event_id` UUID string set by the tracker, a set of timestamps, and other ubiquitous properties such as the `namespace`. You can find out more about how events and entities are structured [here](/docs/events/index.md). ## Auto-tracked entities @@ -207,7 +207,7 @@ Set the application ID using the `appId` field of the [tracker configuration o ### Setting application platform -Set the application platform using the `platform` field of the [tracker configuration object](../tracker-setup/initialization-options/index.md). This will be attached to every event the tracker fires. Its default value is “web”. For a list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters). +Set the application platform using the `platform` field of the [tracker configuration object](../tracker-setup/initialization-options/index.md). This will be attached to every event the tracker fires. Its default value is “web”. For a list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md#application-parameters). ### Setting the user ID diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/link-click/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/link-click/index.md index 40bc72c5f1..9863e20d74 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/link-click/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/link-click/index.md @@ -24,13 +24,13 @@ Link click events are **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/optimizely/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/optimizely/index.md index d6879f68c9..9488cf00d0 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/optimizely/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/optimizely/index.md @@ -24,13 +24,13 @@ Support for OptimizelyX has been introduced in the tracker, you can have a look | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. @@ -76,13 +76,13 @@ If you’re planning on leveraging the entity’s variation names, you’ll have | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. @@ -157,13 +157,11 @@ OptimizelyPlugin( Adding this plugin will automatically capture the following context entities: | Context | -|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [iglu:com.optimizely.snowplow/optimizely_summary/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/blob/master/schemas/com.optimizely.snowplow/optimizely_summary/jsonschema/1-0-0) | -[iglu:com.optimizely/experiment/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/tree/master/schemas/com.optimizely/experiment/jsonschema) | -[iglu:com.optimizely/state/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/tree/master/schemas/com.optimizely/state/jsonschema/1-0-0) | -[iglu:com.optimizely/variation/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/tree/master/schemas/com.optimizely/variation/jsonschema/1-0-0) | -[iglu:com.optimizely/visitor/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/tree/master/schemas/com.optimizely/visitor/jsonschema/1-0-0) | -[iglu:com.optimizely/visitor_audience/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/tree/master/schemas/com.optimizely/visitor_audience/jsonschema/1-0-0) | -[iglu:com.optimizely/visitor_dimension/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/tree/master/schemas/com.optimizely/visitor_dimension/jsonschema/1-0-0) | - - +| [iglu:com.optimizely/experiment/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/tree/master/schemas/com.optimizely/experiment/jsonschema) | +| [iglu:com.optimizely/state/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/tree/master/schemas/com.optimizely/state/jsonschema/1-0-0) | +| [iglu:com.optimizely/variation/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/tree/master/schemas/com.optimizely/variation/jsonschema/1-0-0) | +| [iglu:com.optimizely/visitor/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/tree/master/schemas/com.optimizely/visitor/jsonschema/1-0-0) | +| [iglu:com.optimizely/visitor_audience/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/tree/master/schemas/com.optimizely/visitor_audience/jsonschema/1-0-0) | +| [iglu:com.optimizely/visitor_dimension/jsonschema/1-0-0](https://github.com/snowplow/iglu-central/tree/master/schemas/com.optimizely/visitor_dimension/jsonschema/1-0-0) | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/privacy-sandbox/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/privacy-sandbox/index.md index 6927c36ca3..7e3df07570 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/privacy-sandbox/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/privacy-sandbox/index.md @@ -30,18 +30,18 @@ The Privacy Sandbox context entity is **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ❌ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-privacy-sandbox@3/dist/index.umd.min.js", ["snowplowPrivacySandbox", "PrivacySandboxPlugin"] ); @@ -58,8 +58,8 @@ window.snowplow('addPlugin', import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { PrivacySandboxPlugin } from '@snowplow/browser-plugin-privacy-sandbox'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ PrivacySandboxPlugin() ], }); ``` diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/site-search/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/site-search/index.md index c3a7a4b2c0..469cad1f0f 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/site-search/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/site-search/index.md @@ -20,13 +20,13 @@ Site search events must be **manually tracked**. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. @@ -62,7 +62,7 @@ newTracker('sp1', '{{collector_url}}', { Use the `trackSiteSearch` method to track users searching your website. Here are its arguments: | **Name** | **Required?** | **Description** | **Type** | -|----------------|---------------|---------------------------------|----------| +| -------------- | ------------- | ------------------------------- | -------- | | `terms` | Yes | Search terms | array | | `filters` | No | Search filters | JSON | | `totalResults` | No | Results found | number | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/social-media/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/social-media/index.md index 3af9e333d9..ef411d629e 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/social-media/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/social-media/index.md @@ -20,13 +20,13 @@ Social media interaction events must be **manually tracked**. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. @@ -64,7 +64,7 @@ Social tracking is used to track the way users interact with Facebook, Twitter a The `trackSocialInteraction` method takes three parameters: | **Parameter** | **Description** | **Required?** | **Example value** | -|---------------|---------------------------------------------------------------|---------------|-----------------------| +| ------------- | ------------------------------------------------------------- | ------------- | --------------------- | | `action` | Social action performed | Yes | 'like', 'retweet' | | `network` | Social network | Yes | 'facebook', 'twitter' | | `target` | Object social action is performed on e.g. page ID, product ID | No | '19.99' | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/timezone-geolocation/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/timezone-geolocation/index.md index 6df41897c5..219fba16ba 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/timezone-geolocation/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/timezone-geolocation/index.md @@ -24,18 +24,18 @@ The timezone property is **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ❌ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-timezone@3/dist/index.umd.min.js", ["snowplowTimezone", "TimezonePlugin"] ); @@ -52,8 +52,8 @@ window.snowplow('addPlugin', import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { TimezonePlugin } from '@snowplow/browser-plugin-timezone'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ TimezonePlugin() ], }); ``` @@ -78,18 +78,18 @@ Geolocation context entities are **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-geolocation@3/dist/index.umd.min.js", ["snowplowGeolocation", "GeolocationtPlugin"], [false] // Enable at load @@ -101,14 +101,14 @@ window.snowplow('addPlugin', - `npm install @snowplow/browser-plugin-geolocation@3` - `yarn add @snowplow/browser-plugin-geolocation@3` -- `pnpm add @snowplow/browser-plugin-geolocation@3` +- `pnpm add @snowplow/browser-plugin-geolocation@3` ```javascript import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { GeolocationPlugin, enableGeolocationContext } from '@snowplow/browser-plugin-geolocation'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ GeolocationPlugin() ], }); diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/timings/generic/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/timings/generic/index.md index 2de104932a..fad86e75bc 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/timings/generic/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/timings/generic/index.md @@ -20,18 +20,18 @@ Timing events must be **manually tracked**. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-site-tracking@3/dist/index.umd.min.js", ["snowplowSiteTracking", "SiteTrackingPlugin"] ); @@ -48,8 +48,8 @@ window.snowplow('addPlugin', import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { SiteTrackingPlugin, trackSiteSearch } from '@snowplow/browser-plugin-site-tracking'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ SiteTrackingPlugin() ], }); ``` @@ -63,7 +63,7 @@ newTracker('sp1', '{{collector_url}}', { Use the `trackTiming` method to track how long something took. Here are its arguments: | **Name** | **Required?** | **Description** | **Type** | -|------------|---------------|--------------------------------|----------| +| ---------- | ------------- | ------------------------------ | -------- | | `category` | Yes | Timing category | string | | `variable` | Yes | Timed variable | string | | `timing` | Yes | Number of milliseconds elapsed | number | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/timings/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/timings/index.md index 67faa3c551..33223e097a 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/timings/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/previous-versions/web-trackers-v3/tracking-events/timings/index.md @@ -36,13 +36,13 @@ Performance navigation timing context entities are **automatically tracked** onc | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ❌ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. @@ -117,13 +117,13 @@ Performance timing context entities are **automatically tracked** once configure | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/testing-debugging/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/testing-debugging/index.md index e2332c16e5..88e8406284 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/testing-debugging/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/testing-debugging/index.md @@ -49,7 +49,7 @@ An example of the output from this plugin: **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ads/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ads/index.md index 6ab36ead7c..f0c638aac9 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ads/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ads/index.md @@ -24,18 +24,18 @@ Snowplow ad events must be **manually tracked**. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-ad-tracking@latest/dist/index.umd.min.js", ["snowplowAdTracking", "AdTrackingPlugin"] ); @@ -44,16 +44,16 @@ window.snowplow('addPlugin', -- `npm install @snowplow/browser-plugin-ad-tracking` -- `yarn add @snowplow/browser-plugin-ad-tracking` -- `pnpm add @snowplow/browser-plugin-ad-tracking` +- `npm install @snowplow/browser-plugin-ad-tracking` +- `yarn add @snowplow/browser-plugin-ad-tracking` +- `pnpm add @snowplow/browser-plugin-ad-tracking` ```javascript import { newTracker } from '@snowplow/browser-tracker'; import { AdTrackingPlugin, trackAdClick } from '@snowplow/browser-plugin-ad-tracking'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ AdTrackingPlugin() ], }); ``` @@ -70,7 +70,7 @@ The ad tracking plugin includes three event types: ad impression, ad click, and Ad impression tracking is accomplished using the `trackAdImpression` method. Here are the arguments it accepts: | **Name** | **Required?** | **Description** | **Type** | -|----------------|---------------|----------------------------------------------------------------------|----------| +| -------------- | ------------- | -------------------------------------------------------------------- | -------- | | `impressionId` | No | Identifier for the particular impression instance | string | | `costModel` | No | The cost model for the campaign: 'cpc', 'cpm', or 'cpa' | string | | `cost` | No | Ad cost | number | @@ -130,7 +130,7 @@ Ad impression events are implemented as Snowplow self describing events. [Here] Ad click tracking is accomplished using the `trackAdClick` method. Here are the arguments it accepts: | **Name** | **Required?** | **Description** | **Type** | -|----------------|---------------|----------------------------------------------------------------------|----------| +| -------------- | ------------- | -------------------------------------------------------------------- | -------- | | `targetUrl` | Yes | The destination URL | string | | `clickId` | No | Identifier for the particular click instance | string | | `costModel` | No | The cost model for the campaign: 'cpc', 'cpm', or 'cpa' | string | @@ -188,7 +188,7 @@ Ad click events are implemented as Snowplow self describing events.[Here](https: Use the `trackAdConversion` method to track ad conversions. Here are the arguments it accepts: | **Name** | **Required?** | **Description** | **Type** | -|----------------|---------------|----------------------------------------------------------------------|----------| +| -------------- | ------------- | -------------------------------------------------------------------- | -------- | | `conversionId` | No | Identifier for the particular conversion instance | string | | `costModel` | No | The cost model for the campaign: 'cpc', 'cpm', or 'cpa' | string | | `cost` | No | Ad cost | number | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/button-click/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/button-click/index.md index 322cc16d0c..39fd58c6f8 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/button-click/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/button-click/index.md @@ -24,7 +24,7 @@ Button click events are **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | @@ -326,7 +326,7 @@ enableButtonClickTracking({ The plugin will track the following data (if present on the element): | Field | Description | Type | Required? | -|-----------|-----------------------------------------------------|------------|-----------| +| --------- | --------------------------------------------------- | ---------- | --------- | | `label` | The text on the button, or a user-provided override | `string` | Yes | | `id` | The ID of the button | `string` | No | | `classes` | The classes of the button | `string[]` | No | @@ -365,7 +365,7 @@ Suppose we have the following button on our page: ```html ``` @@ -400,7 +400,7 @@ Suppose we have the following button on our page: ```html ``` diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/client-hints/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/client-hints/index.md index b3470c17bb..d9b0fd30f3 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/client-hints/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/client-hints/index.md @@ -31,18 +31,18 @@ The Client Hints context entity is **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ❌ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-client-hints@latest/dist/index.umd.min.js", ["snowplowClientHints", "ClientHintsPlugin"] ); @@ -59,9 +59,9 @@ window.snowplow('addPlugin', import { newTracker } from '@snowplow/browser-tracker'; import { ClientHintsPlugin } from '@snowplow/browser-plugin-client-hints'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', - plugins: [ ClientHintsPlugin() ], +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', + plugins: [ ClientHintsPlugin() ], // Use ClientHintsPlugin(true) to capture high entropy values }); ``` diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ecommerce/enhanced/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ecommerce/enhanced/index.md index 704b01c0bd..951d9d9fd5 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ecommerce/enhanced/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ecommerce/enhanced/index.md @@ -24,13 +24,13 @@ Enhanced ecommerce events must be **manually tracked**. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ❌ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. @@ -68,7 +68,7 @@ The enhanced ecommerce plugin is based around the `EnhancedEcommerceAction` even Use the `trackEnhancedEcommerceAction` method to track a GA Enhanced Ecommerce Action. When this function is called all of the added Ecommerce context entities are attached to this action and flushed from the tracker. | **Name** | **Required?** | **Type** | -|----------|---------------|----------| +| -------- | ------------- | -------- | | `action` | Yes | string | The allowed actions: @@ -124,7 +124,7 @@ The enhanced ecommerce context entities are specific to this plugin, and cannot Use the `addEnhancedEcommerceActionContext` method to add a GA Enhanced Ecommerce Action Context to the Tracker: | **Name** | **Required?** | **Type** | -|---------------|---------------|-------------------| +| ------------- | ------------- | ----------------- | | `id` | Yes | string | | `affiliation` | No | string | | `revenue` | No | number OR string | @@ -190,7 +190,7 @@ addEnhancedEcommerceActionContext({ Use the `addEnhancedEcommerceImpressionContext` method to add a GA Enhanced Ecommerce Impression Context to the Tracker: | **Name** | **Required?** | **Type** | -|------------|---------------|-------------------| +| ---------- | ------------- | ----------------- | | `id` | Yes | string | | `name` | No | string | | `list` | No | string | @@ -255,7 +255,7 @@ addEnhancedEcommerceImpressionContext({ Use the `addEnhancedEcommerceProductContext` method to add a GA Enhanced Ecommerce Product Field Context: | **Name** | **Required?** | **Type** | -|------------|---------------|-------------------| +| ---------- | ------------- | ----------------- | | `id` | Yes | string | | `name` | No | string | | `list` | No | string | @@ -320,7 +320,7 @@ addEnhancedEcommerceProductContext({ Use the `addEnhancedEcommercePromoContext` method to add a GA Enhanced Ecommerce Promotion Field Context: | **Name** | **Required?** | **Type** | -|------------|---------------|----------| +| ---------- | ------------- | -------- | | `id` | Yes | string | | `name` | No | string | | `creative` | No | string | @@ -366,4 +366,3 @@ addEnhancedEcommercePromoContext({ - diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/element-tracking/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/element-tracking/index.md new file mode 100644 index 0000000000..29d55b28eb --- /dev/null +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/element-tracking/index.md @@ -0,0 +1,816 @@ +--- +title: "Element tracking" +sidebar_position: 55 +--- + +# Element visibility and lifecycle tracking + +```mdx-code-block +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +``` + +Element tracking enables declarative tracking of page elements existing on web pages and scrolling into view. + +The plugin lets you define rules for which elements to track, and lets you trigger events for any combination of: + +- New matching elements get added to a page +- Existing elements get changed to match a rule +- Matching elements get scrolled into a user's view and become visible +- Matching elements get scrolled out of a user's view and become no longer visible +- Elements get changed to no longer match a rule +- Matching elements get removed from a page + +As a configuration-based plugin, you only need to define which elements should generate events, and in which scenarios. +You can reuse the same configuration for generic tracking across a varying number of pages or sites. + +Each event contains information about the matching element, and you can configure extra details to extract to allow dynamic event payloads. + +Example use cases for these events include: + +- Funnel steps (form on page > form in view > [form tracking events](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/form-tracking/index.md)) +- List impression tracking (product impressions) +- Component performance (recommendations performance, newsletter sign-up forms, modal popups) +- Product usage (elements that appear on-hover, labeling or grouping events related to specific features) +- Advertisement impression tracking + +## Install plugin + + + + +| Tracker Distribution | Included | +| -------------------- | -------- | +| `sp.js` | ❌ | +| `sp.lite.js` | ❌ | + +**Download:** + +
Download from GitHub Releases (Recommended)GitHub Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+ +:::note + +The links to the CDNs point to the current latest version. +You should pin to a specific version when integrating this plugin on your website if you are using a third-party CDN in production. + +::: + + + + +- `npm install @snowplow/browser-plugin-element-tracking` +- `yarn add @snowplow/browser-plugin-element-tracking` +- `pnpm add @snowplow/browser-plugin-element-tracking` + + + + +## Examples + +Here are some example rules for simple use cases on the [Snowplow website](https://snowplow.io/) ([snapshot at time of writing](https://web.archive.org/web/20250422013533/https://snowplow.io/)). + +The code examples use the [JavaScript Tracker syntax](/docs/sources/trackers/javascript-trackers/web-tracker/index.md), but should easily adapt to Browser Tracker syntax if needed. + +
+ Scroll sections + + The homepage has content grouped into distinct "layers" as you scroll down the page. + To see when users scroll down to each section, you can track an `expose` event for each section. + You can capture the header element text to identify each one. + + ```javascript title="Rule configuration" + snowplow('startElementTracking', { + elements: { + selector: "section", + expose: { when: "element" }, + details: { child_text: { title: "h2" } } + } + }); + ``` + + ```json title="Event: expose_event" + { + "schema": "iglu:com.snowplowanalytics.snowplow/element/jsonschema/1-0-0", + "data": { + "element_name": "section", + "width": 1920, + "height": 1111.7333984375, + "position_x": 0, + "position_y": 716.4500122070312, + "doc_position_x": 0, + "doc_position_y": 716.4500122070312, + "element_index": 2, + "element_matches": 10, + "originating_page_view": "06dbb0a2-9acf-4ae4-9562-1469b6d12c5d", + "attributes": [ + { + "source": "child_text", + "attribute": "title", + "value": "Why Data Teams Choose Snowplow" + } + ] + } + } + ``` + + ```json title="Event: expose_event" + { + "schema": "iglu:com.snowplowanalytics.snowplow/element/jsonschema/1-0-0", + "data": { + "element_name": "section", + "width": 1920, + "height": 2880, + "position_x": 0, + "position_y": 896.683349609375, + "doc_position_x": 0, + "doc_position_y": 1828.183349609375, + "element_index": 3, + "element_matches": 10, + "originating_page_view": "06dbb0a2-9acf-4ae4-9562-1469b6d12c5d", + "attributes": [ + { + "source": "child_text", + "attribute": "title", + "value": "How Does Snowplow Work?" + } + ] + } + } + ``` + +
+ +
+ Content depth + + The blog posts have longer-form content. + Snowplow's page ping events track scroll depth by pixels, but those measurements become inconsistent between devices and page. + To see how much content gets consumed, you can generate stats based on the paragraphs in the content. + You can also get periodic stats based on the entire article in page pings. + + ```javascript title="Rule configuration" + snowplow('startElementTracking', { + elements: [ + { + selector: ".blogs_blog-post-body_content", + name: "blog content", + expose: false, + includeStats: ["page_ping"] + }, + { + selector: ".blogs_blog-post-body_content p", + name: "blog paragraphs" + } + ] + }); + ``` + + Because the expose event contains the `element_index` and `element_matches`, you can easily query the largest `element_index` by page view ID. + The result tells you consumption statistics for individual views of each article. + You can then summarize that metric to the content or category level, or converted to a percentage by comparing with `element_matches`. + + ```json title="Event: expose_event" + { + "schema": "iglu:com.snowplowanalytics.snowplow/contexts/jsonschema/1-0-0", + "data": [ + { + "schema": "iglu:com.snowplowanalytics.snowplow/element/jsonschema/1-0-0", + "data": { + "element_name": "blog paragraphs", + "width": 800, + "height": 48, + "position_x": 320, + "position_y": 533.25, + "doc_position_x": 320, + "doc_position_y": 1373, + "element_index": 6, + "element_matches": 24, + "originating_page_view": "f390bec5-f63c-48af-b3ad-a03f0511af7f", + "attributes": [] + } + }, + { + "schema": "iglu:com.snowplowanalytics.snowplow/web_page/jsonschema/1-0-0", + "data": { + "id": "f390bec5-f63c-48af-b3ad-a03f0511af7f" + } + } + ] + } + ``` + + The periodic page ping events also give you a summary of the total progress in the `max_y_depth_ratio`/`max_y_depth` values. + With `y_depth_ratio` you can also see when users backtrack up the page. + + ```json title="Event: page_ping" + { + "schema": "iglu:com.snowplowanalytics.snowplow/element_statistics/jsonschema/1-0-0", + "data": { + "element_name": "blog content", + "element_index": 1, + "element_matches": 1, + "current_state": "unknown", + "min_size": "800x3928", + "current_size": "800x3928", + "max_size": "800x3928", + "y_depth_ratio": 0.20302953156822812, + "max_y_depth_ratio": 0.4931262729124236, + "max_y_depth": "1937/3928", + "element_age_ms": 298379, + "times_in_view": 0, + "total_time_visible_ms": 0 + } + } + ``` + +
+ +
+ Simple funnels + + A newsletter sign-up form exists at the bottom of the page. + Performance measurement becomes difficult because many visitors don't even see it. + To test this you first need to know: + + - When the form exists on a page + - When the form is actually seen + - When people actually interact with the form + - When the form is finally submitted + + The form tracking plugin can only do the last parts, but the element tracker gives you the earlier steps. + If you end up adding more forms in the future, you'll want to know which is which, so you can mark the footer as a component so you can split it out later. + + ```javascript title="Rule configuration" + snowplow('startElementTracking', { + elements: [ + { + selector: ".hbspt-form", + name: "newsletter signup", + create: true, + }, + { + selector: "footer", + component: true, + expose: false + } + ] + }); + ``` + + If you try this on a blog page, you actually get two `create_element` events. + Blog posts have a second newsletter sign-up in a sidebar next to the content. + Because only the second form is a member of the `footer` component, you can easily see which one you are trying to measure when you query the data later. + + ```json title="Event: create_element" + { + "schema": "iglu:com.snowplowanalytics.snowplow/contexts/jsonschema/1-0-0", + "data": [ + { + "schema": "iglu:com.snowplowanalytics.snowplow/element/jsonschema/1-0-0", + "data": { + "element_name": "newsletter signup", + "width": 336, + "height": 161, + "position_x": 1232, + "position_y": 238.88333129882812, + "doc_position_x": 1232, + "doc_position_y": 3677.883331298828, + "element_index": 1, + "element_matches": 2, + "originating_page_view": "02e30714-a84a-42f8-8b07-df106d669db0", + "attributes": [] + } + }, + { + "schema": "iglu:com.snowplowanalytics.snowplow/web_page/jsonschema/1-0-0", + "data": { + "id": "02e30714-a84a-42f8-8b07-df106d669db0" + } + } + ] + } + ``` + + ```json title="Event: create_element" + { + "schema": "iglu:com.snowplowanalytics.snowplow/contexts/jsonschema/1-0-0", + "data": [ + { + "schema": "iglu:com.snowplowanalytics.snowplow/element/jsonschema/1-0-0", + "data": { + "element_name": "newsletter signup", + "width": 560, + "height": 137, + "position_x": 320, + "position_y": 1953.5, + "doc_position_x": 320, + "doc_position_y": 5392.5, + "element_index": 2, + "element_matches": 2, + "originating_page_view": "02e30714-a84a-42f8-8b07-df106d669db0", + "attributes": [] + } + }, + { + "schema": "iglu:com.snowplowanalytics.snowplow/component_parents/jsonschema/1-0-0", + "data": { + "element_name": "newsletter signup", + "component_list": [ + "footer" + ] + } + }, + { + "schema": "iglu:com.snowplowanalytics.snowplow/element/jsonschema/1-0-0", + "data": { + "element_name": "footer", + "width": 1920, + "height": 1071.5, + "position_x": 0, + "position_y": 1212, + "doc_position_x": 0, + "doc_position_y": 4651, + "originating_page_view": "", + "attributes": [] + } + }, + { + "schema": "iglu:com.snowplowanalytics.snowplow/web_page/jsonschema/1-0-0", + "data": { + "id": "02e30714-a84a-42f8-8b07-df106d669db0" + } + } + ] + } + ``` + +
+ +
+ Recommendations performance + + The homepage contains a section for the "Latest Blogs from Snowplow." + This could represent recommendations or some other form of personalization. + If it did, one might want to optimize it. + Link tracking could tell you when a recommendation worked and a visitor clicked it, but how would identify the recommendation not encouraging clicks? + If you track when the widget becomes visible and include the items that got recommended, you could correlate that with the clicks to measure performance. + For fairer measurement of visibility, you can configure that visibility only counts if at least 50% is in view, and it has to be on screen for at least 1.5 seconds. + You'll also collect the post title and author information. + + + ```javascript title="Rule configuration" + snowplow('startElementTracking', { + elements: [ + { + selector: ".blog_list-header_list-wrapper", + name: "recommended_posts", + create: true, + expose: { when: "element", minTimeMillis: 1500, minPercentage: 0.5 }, + contents: [ + { + selector: ".collection-item", + name: "recommended_item", + details: { child_text: { title: "h3", author: ".blog_list-header_author-text > p" } } + } + ] + } + ] + }); + ``` + + Scrolling down to see the items and you see the items that get served to the visitor: + + ```json title="Event: expose_element" + { + "schema": "iglu:com.snowplowanalytics.snowplow/contexts/jsonschema/1-0-0", + "data": [ + { + "schema": "iglu:com.snowplowanalytics.snowplow/element/jsonschema/1-0-0", + "data": { + "element_name": "recommended_posts", + "width": 1280, + "height": 680.7666625976562, + "position_x": 320, + "position_y": 437.70001220703125, + "doc_position_x": 320, + "doc_position_y": 6261.066711425781, + "element_index": 1, + "element_matches": 1, + "originating_page_view": "034db1d6-1d60-42ca-8fe1-9aafc0442a22", + "attributes": [] + } + }, + { + "schema": "iglu:com.snowplowanalytics.snowplow/element_content/jsonschema/1-0-0", + "data": { + "element_name": "recommended_item", + "parent_name": "recommended_posts", + "parent_position": 1, + "position": 1, + "attributes": [ + { + "source": "child_text", + "attribute": "title", + "value": "Data Pipeline Architecture Patterns for AI: Choosing the Right Approach" + }, + { + "source": "child_text", + "attribute": "author", + "value": "Matus Tomlein" + } + ] + } + }, + { + "schema": "iglu:com.snowplowanalytics.snowplow/element_content/jsonschema/1-0-0", + "data": { + "element_name": "recommended_item", + "parent_name": "recommended_posts", + "parent_position": 1, + "position": 2, + "attributes": [ + { + "source": "child_text", + "attribute": "title", + "value": "Data Pipeline Architecture For AI: Why Traditional Approaches Fall Short" + }, + { + "source": "child_text", + "attribute": "author", + "value": "Matus Tomlein" + } + ] + } + }, + { + "schema": "iglu:com.snowplowanalytics.snowplow/element_content/jsonschema/1-0-0", + "data": { + "element_name": "recommended_item", + "parent_name": "recommended_posts", + "parent_position": 1, + "position": 3, + "attributes": [ + { + "source": "child_text", + "attribute": "title", + "value": "Agentic AI Applications: How They Will Turn the Web Upside Down" + }, + { + "source": "child_text", + "attribute": "author", + "value": "Yali\tSassoon" + } + ] + } + }, + { + "schema": "iglu:com.snowplowanalytics.snowplow/web_page/jsonschema/1-0-0", + "data": { + "id": "034db1d6-1d60-42ca-8fe1-9aafc0442a22" + } + } + ] + } + ``` + +
+ +## Enable element tracking + +You can begin tracking elements by providing configuration to the plugin's `startElementTracking` method: + + + + +```javascript +window.snowplow('addPlugin', + "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-element-tracking@latest/dist/index.umd.min.js", + ["snowplowElementTracking", "SnowplowElementTrackingPlugin"] +); + +snowplow('startElementTracking', { elements: [/* configuration */] }); +``` + + + + +Element tracking is part of a separate plugin, `@snowplow/browser-plugin-element-tracking`. You need to install it with your favorite package manager: `npm install @snowplow/browser-plugin-element-tracking` and then initialize it: + +```javascript +import { newTracker } from '@snowplow/browser-tracker'; +import { SnowplowElementTrackingPlugin, startElementTracking } from '@snowplow/browser-plugin-element-tracking'; + +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', + plugins: [ SnowplowElementTrackingPlugin() ], +}); + +startElementTracking({ elements: [/* configuration */] }); +``` + + + +Each use of this method adds the given list of element rules to the plugin configuration to start automatically tracking events. + +The `elements` configuration can take a single rule or an array of rules. + +Beyond `elements`, you can also specify `context`: an array of static entities or entity-generating functions to include custom information with all events generated by the plugin. +This can also exist at the individual rule level for more specific entity requirements. + +For the specifics of rule configuration, see [Rule configuration](#rule-configuration) below. + +## Disabling element tracking + +To turn off tracking, use `endElementTracking` to remove the rule configuration. +Providing no options to `endElementTracking` removes all earlier configured rules. +If all rules get removed, the plugin removes its listeners until new rules get configured. + +If you want to stop tracking based for specific rules, you can provide the `name` or `id` values to the `endElementTracking` method. +Each rule provided to `startElementTracking` gets associated with a `name` - and optionally, an `id`. +If you don't specify a `name`, the `name` defaults to the `selector` value (required for all rules). + +For more complex requirements, you can also specify a callback function to decide if a rule should turn off (callback returns `true`) or not (callback returns `false`). + + + + +```javascript +snowplow('endElementTracking', { elements: ['name1', 'name2'] }); // removes based on `name` matching; multiple rules may share a name +snowplow('endElementTracking', { elementIds: ['id1'] }); // removes rules based on `id` matching; at most one rule can have the same `id` +snowplow('endElementTracking', { filter: (rule) => /recommendations/i.test(rule.name) }); // more complicated matching; rules where the `filter` function returns true will be removed +snowplow('endElementTracking'); // remove all configured rules +``` + + + + +```javascript +endElementTracking({ elements: ['name1', 'name2'] }); // removes based on `name` matching; multiple rules may share a name +endElementTracking({ elementIds: ['id1'] }); // removes rules based on `id` matching; at most one rule can have the same `id` +endElementTracking({ filter: (rule) => /recommendations/i.test(rule.name) }); // more complicated matching; rules where the `filter` function returns true will be removed +endElementTracking(); // remove all configured rules +``` + + + +Removing rules by name removes all rules with matching names - rule names don't require uniqueness. +Rule IDs _must be_ unique, so only a single rule matches per `elementIds` value. +If you specify more than one of the `elementIds`, `elements`, and `filter` options, they get evaluated in that order. +Passing an empty object to `endElementTracking` counts as specifying no options - and removes no rules - which differs to calling it with no arguments. + +## Rule configuration + +When calling `startElementTracking`, you specify the `elements` option with either a single rule or an array of rules. +Each rule defines core information like: the elements to match, events to fire, extra details to collect about each element (or their contents), and custom entities to attach. + +### Core configuration + +The foundational configuration required for working with the plugin APIs. + +| Rule property | Type | Description | Status | +| ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | +| `selector` | `string` | A CSS selector string that matches one or more elements on the page that should trigger events from this rule. | **Required** | +| `name` | `string` | A label to name this rule. Allows you to keep a stable name for events generated by this rule, even if the `selector` changes, so the data produced remains consistent. You can share a single `name` between many rules to have different configurations for different selectors. If not supplied, the `selector` value becomes the `name`. | _Recommended_ | +| `id` | `string` | A specific identifier for this rule. Useful if you share a `name` between many rules and need to specifically remove individual rules within that group. | Optional | + +### Event configuration + +These settings define which events should automatically fire, and the situations when they should occur. +By default, only the `expose` setting gets enabled, so the plugin tracks when elements matching the rule's `selector` become visible on the user's viewport. +For convenience, each option can use a boolean to turn on or off each event type for elements matching the selector. +You can also use an object to have more control on when the events get triggered. + +| Rule property | Type | Description | Default | +| ------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------- | +| `create` | `boolean` or `object` | Controls firing `element_create` events when the element gets added to the page (or already exists when the rule gets configured). | `false` | +| `destroy` | `boolean` or `object` | Controls firing `element_destroy` events when the element gets removed from the page. | `false` | +| `expose` | `boolean` or `object` | Controls firing `element_expose` events when the element becomes visible in the user's viewport. | `true` | +| `obscure` | `boolean` or `object` | Controls firing `element_obscure` events when the element becomes no longer visible in the user's viewport. | `false` | + +#### General event options + +These common options are available for the `create`, `destroy`, `expose`, and `obscure` settings and allow limiting how often the event fires. + +| Rule property | Type | Description | Status | +| ------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------ | +| `when` | `string` or `object` | Sets the limit on how many times the event should fire for matched elements. | **Required** | +| `condition` | `array` | A single or list of many [data selectors](#data-selectors); if the final result has no elements the event won't trigger. | Optional | + +For `when`, the available options include, in descending order of frequency: + +- `always`: generate an event every time an element becomes eligible (for example, every time an event becomes visible) +- `element`: only fire 1 event for each specific element that matches the rule for the lifetime of the rule (for example, just the first time each element becomes visible) +- `pageview`: like `element`, but reset the state when the tracker next tracks a page view event; this can be useful for single page applications where the plugin may have a long lifetime but you still want to limit the number of events +- `once`: only fire 1 event _per rule_, so even if there are many elements matching `selector` only track the first time this occurs +- `never`: never track this event for this rule. This is useful for defining `components` + +When using the `boolean` shorthand, `true` is identical to `{ when: "always" }`, and `false` is `{ when: "never" }`. + +#### Expose event options + +As well as the [general event options](#general-event-options), `expose` has some extra options specific to its use case. + +| Rule property | Type | Description | +| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `minPercentage` | `number` | For larger elements, only consider the element visible if at least this percentage of its area is visible. | +| `minTimeMillis` | `number` | Only consider the element visible if it's cumulative time on screen exceeds this value, in milliseconds. | +| `minSize` | `number` | Unless the elements area (height * width) is at least this size, don't consider the element as visible (for example, don't track empty elements). | +| `boundaryPixels` | `number` or `array` | Add this number of pixels to the dimensions (top, right, bottom, left) of the element when calculating its dimensions for `minPercentage` purposes. You can specify a single value, a pair for vertical and horizontal values, or specific values for each of top, right, bottom, and left. | + +### Shadow DOM compatibility + +If the elements you want to track exist within [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) trees, the plugin may not identify them. +Use these settings to notify the plugin that it should descend into shadow hosts to identify elements to match the rule against. + +| Rule property | Type | Description | +| ---------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `shadowSelector` | `string` | A CSS selector for elements that are shadow hosts containing the actual `selector`-targeted elements. | +| `shadowOnly` | `boolean` | By default, the plugin matches `selector` elements both outside and inside shadow hosts matched by `shadowSelector`; set this to `true` to only match elements within shadow hosts matched by `shadowSelector`. (for example, you may want all `button` elements in a web component, but that selector is too generic when applied to your whole site, so this setting can limit the matches to only those within those shadow hosts). | + +### Element data + +These settings control extra information captured about the event generating the event. + +| Rule property | Type | Description | +| -------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `component` | `boolean` | When `true`, defines these elements as being a component. Events generated by this rule, or other rules targeting their child elements, have this rules `name` attached via the `component_parents` entity, showing the component hierarchy that the element belongs to. | +| `details` | `array` | A list of [data selectors](#data-selectors) of information to capture about this element. The selected values populate the `attributes` object in the [`element` entity](#events-and-entities). | +| `includeStats` | `array` | An array of `event_name` values that the plugin should attach an [`element_statistics` entity](#element-statistics) to. | +| `contents` | `array` | You can nest configurations in this property to collect data about elements nested within the elements matched by this rule (for example, this rule could target a recommendations widget, and using `contents` you could describe the individual recommendations served within it). The nested configurations can not trigger their own events, and their [event configuration](#event-configuration) gets ignored. Nested `details` work for the extra `element_content` entities that get generated (based on the nested `name`), and you can further nest `contents` arbitrarily, though you may end up with a large number of entities. | + +## Data selectors + +Data selectors are a declarative way to extract information from elements matched by rules. + +The plugin uses data selectors when deciding if an element should trigger an event (using [`condition`](#general-event-options)), or when building the `element` entity's `attributes` property based on a rule's [`details` and `contents` settings](#element-data). + +The declarative configuration lets you safely extract information without having to explicitly write code, or still get information where callbacks aren't possible. +For example, a function defined in Google Tag Manager that passes through a Tag Template can not work with DOM elements directly, which limits the data it could extract. + +The declarative use is optional, and you can also just provide a callback function that accepts an element and returns an object if you prefer. + +You define data selectors as a list, so you can also combine the two approaches. +When evaluating each list of data selectors, the result is a list of triplets describing: + +1. The `source`/type of the data selector +2. The selected `attribute` name +3. The selected attribute `value` + +Each data selector should be a function or an object with any of the following properties: + +| Data selector property | Value type | Description | +| ---------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| | `function` | A custom callback. The function should return an object with `string` properties, each of which produce a result in the output list. Values get cast to `string`; empty values (such as `undefined`) get skipped entirely. | +| `attributes` | `array` | Produces a result for each provided attribute extracted via the [`getAttribute()` API](https://developer.mozilla.org/en-US/docs/Web/API/Element/getAttribute). The value is often the initial value set in the HTML of the page, compared to `properties` which may be a more recent value. | +| `properties` | `array` | Produces a result for each provided property name sourced from the element. | +| `dataset` | `array` | Produces a result for each provided property name sourced from the element's dataset attribute. This should be the camel-case format version, rather than the attribute-style name. | +| `child_text` | `object` | The value should be an object mapping names to CSS selectors; produces a result for each name mapped to the `textContent` of the first matching child element. Be cautious of large text values. | +| `content` | `object` | The value should be an object mapping names to regular expression patterns. Each pattern gets evaluated against the `textContent` of the matching element and produces an attribute with the matched value. If the pattern contains matching groups, uses the first captured group. | +| `selector` | `boolean` | Attach the rule's `selector` as an attribute. Can be useful if you are sharing `names` between rules and need to know which rule matched. | +| `match` | `object` | The value should be an object mapping other attribute names to values or functions. The current set of attribute results get checked against this object; if no attributes have the same value (or the function doesn't return `true` for the value) then discard the current list of results. This can be useful for the `condition` setting. | + +The `source` matches the property used, or `callback` if a callback function is the source. +If the callback encounters an error, it produces an `error`-sourced value. + +For the purposes of `condition` matching, events don't fire if the resulting list of attributes is empty. + +## Events and entities + +Events generated by the plugin have simple payloads, consisting of an `element_name` property that's referenced by the entities attached to the event. + +The event schemas are: + +- [`create_element`](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/create_element/jsonschema/1-0-0) +- [`destroy_element`](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/destroy_element/jsonschema/1-0-0) +- [`expose_element`](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/expose_element/jsonschema/1-0-0) +- [`obscure_element`](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/obscure_element/jsonschema/1-0-0) + +These events include an `element` entity which includes: + +- An `element_name` matching the one in the event payload +- Size and position information +- Any attributes collected via the [`detail` setting](#element-data) + +```json reference title="Entity - iglu:com.snowplowanalytics.snowplow/element/jsonschema/1-0-0" referenceLinkText="See schema on GitHub" +https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/element/jsonschema/1-0-0 +``` + +### Optional entities + +Depending on configuration, events may also include the following entities: + +#### Element statistics + +By using the [`includeStats` setting](#element-data), you can configure the plugin to attach this entity to any events sent to the tracker (including those not generated by this plugin). + +For each rule with this configured, entities for each matching element include: + +- Visibility state at the time of the event +- Smallest, largest, and current size +- Element-specific min/max scroll depth information +- Time since the element was first observed (element age) +- How many times the element has been in view +- Cumulative total time the element has been in view + +If the selector matches a lot of elements, this can enlarge event payload sizes, use caution with the `selector` used with this setting. + +Note that `includeStats` requires opt-in for all event types, even those generated by this plugin: + + + + +```javascript +snowplow('startElementTracking', { elements: { + selector: 'main.article', + name: 'article_content', + includeStats: ['expose_element', 'page_ping'] +} }); +``` + + + + +```javascript +import { SnowplowElementTrackingPlugin, startElementTracking } from '@snowplow/browser-plugin-element-tracking'; + +startElementTracking({ elements: { + selector: 'main.article', + name: 'article_content', + includeStats: ['expose_element', 'page_ping'] +} }); +``` + + + +Define non-self-describing events with the event names assigned to them during enrichment (`page_view`, `page_ping`, `event` (structured events), `transaction`, and `transaction_item`). + +```json reference title="Entity - iglu:com.snowplowanalytics.snowplow/element_statistics/jsonschema/1-0-0" referenceLinkText="See schema on GitHub" +https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/element_statistics/jsonschema/1-0-0 +``` + +#### Component hierarchy + +If any configured rules are a [`component`](#element-data), events generated by the plugin may include the `component_parents` entity. + +This includes an `element_name` reference, and a `component_list` that's a list of any `component`-rule names that are ancestors of that element. +Use these values to aggregate events to different levels of a component hierarchy. + +The plugin also exposes a `getComponentListGenerator` command, that returns a function that accepts an element and returns this entity. +This function gets used to attach the entity to custom events, or events generated by other plugins like the [form](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/form-tracking/index.md) or [link](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/link-click/index.md) tracking plugins. + + + + +```javascript +snowplow('getComponentListGenerator', function (componentGenerator, componentGeneratorWithDetail) { + // access a context generator aware of the startElementTracking "components" configuration + // this will attach the component_parents entity to events generated by these plugins that show the component hierarchy + snowplow('enableLinkClickTracking', { context: [componentGenerator] }); + snowplow('enableFormTracking', { context: [componentGenerator] }); + + // componentGeneratorWithDetail will also populate element_detail entities for each component, but is not directly compatible with the above plugin APIs +}); +``` + + + + +```javascript +import { getComponentListGenerator } from '@snowplow/browser-plugin-element-tracking'; +import { enableLinkClickTracking } from '@snowplow/browser-plugin-link-click-tracking'; +import { enableFormTracking } from '@snowplow/browser-plugin-form-tracking'; + +// access a context generator aware of the startElementTracking "components" configuration +const [componentGenerator, componentGeneratorWithDetail] = getComponentListGenerator(); + +// this will attach the component_parents entity to events generated by these plugins that show the component hierarchy +enableLinkClickTracking({ options: { ... }, psuedoClicks: true, context: [componentGenerator] }); +enableFormTracking({ context: [componentGenerator] }); + +// componentGeneratorWithDetail will also populate element_detail entities for each component, but is not directly compatible with the above plugin APIs +``` + + + +```json reference title="Entity - iglu:com.snowplowanalytics.snowplow/component_parents/jsonschema/1-0-0" referenceLinkText="See schema on GitHub" +https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/component_parents/jsonschema/1-0-0 +``` + +#### Element contents + +The `element_content` schema gets attached when you use the [`contents` setting](#element-data). + +There can be many instances of this entity in individual events, and the list of them are a flattened tree representation of the nested configuration provided. +Each instance contains references to the parent `element_content` or `element` entity instance that contains it in the `parent_name` and `parent_index` properties (via `element_name` and `element_index`, respectively). +Nested `details` configurations are also used to populate the `attributes` for each instance. + +```json reference title="Entity - iglu:com.snowplowanalytics.snowplow/element_content/jsonschema/1-0-0" referenceLinkText="See schema on GitHub" +https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/element_content/jsonschema/1-0-0 +``` + +#### Custom context + +You can attach custom entities to the events generated by the plugin. + +- You can include `context` alongside `elements` when calling `startElementTracking`. You can pass an array of static entities _or_ a callback function that returns such an array. The function receives the element that the event is relevant to, and the matching rule that defined the event should fire. +- Individual rules may also contain specific `context` in the same format as in the preceding. diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/errors/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/errors/index.md index b45fd0ceba..0e26977e34 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/errors/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/errors/index.md @@ -20,18 +20,18 @@ Error events can be **manually tracked** and/or **automatically tracked**. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-error-tracking@latest/dist/index.umd.min.js", ["snowplowErrorTracking", "ErrorTrackingPlugin"] ); @@ -48,8 +48,8 @@ window.snowplow('addPlugin', import { newTracker } from '@snowplow/browser-tracker'; import { ErrorTrackingPlugin, enableErrorTracking } from '@snowplow/browser-plugin-error-tracking'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ ErrorTrackingPlugin() ], }); @@ -103,7 +103,7 @@ trackError({ | **Name** | **Required?** | **Description** | **Type** | -|------------|---------------|-------------------------------------|------------| +| ---------- | ------------- | ----------------------------------- | ---------- | | `message` | Yes | Error message | string | | `filename` | No | Filename or URL | string | | `lineno` | No | Line number of problem code chunk | number | @@ -183,7 +183,7 @@ enableErrorTracking({ | **Name** | **Required?** | **Description** | **Type** | -|----------------|---------------|---------------------------------|---------------------------------------------| +| -------------- | ------------- | ------------------------------- | ------------------------------------------- | | `filter` | No | Predicate to filter exceptions | `(ErrorEvent) => Boolean` | | `contextAdder` | No | Function to get dynamic context | `(ErrorEvent) => Array` | | context | No | Additional custom context | `Array` | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/event-specifications/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/event-specifications/index.md index 9ab2b8caed..c701c13e8e 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/event-specifications/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/event-specifications/index.md @@ -15,7 +15,7 @@ The plugin allows you to integrate with Event Specifications for a selected set The plugin will automatically add an Event Specification context to the events matching the configuration added. :::note -The plugin is available since version 3.23 of the tracker. +The plugin is available since version 3.23 of the tracker and is currently only available for Data Products created using the [Media Web template](/docs/data-product-studio/data-products/data-product-templates/#media-web). ::: ## Install plugin diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/form-tracking/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/form-tracking/index.md index 87fa5d8d7f..f45ef9be58 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/form-tracking/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/form-tracking/index.md @@ -25,12 +25,12 @@ Form events are **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ga-cookies/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ga-cookies/index.md index 8e6f6ddd17..3070ac4e02 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ga-cookies/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/ga-cookies/index.md @@ -20,13 +20,13 @@ GA cookies information is **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. @@ -81,9 +81,9 @@ interface GACookiesPluginOptions { ``` | Name | Default | Description | -|------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| ua | `false` | Send Universal Analytics specific cookie values. | -| ga4 | `true` | Send Google Analytics 4 specific cookie values. | +| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ua | `false` | Send Universal Analytics specific cookie values. | +| ga4 | `true` | Send Google Analytics 4 specific cookie values. | | ga4MeasurementId | `""` | Measurement id(s) to search the Google Analytics 4 session cookie. Can be a single measurement id as a string or an array of measurement id strings. The cookie has the form of `_ga_` where `` is the data stream container id and `` is the optional `cookie_prefix` option of the gtag.js tracker. | | cookiePrefix | `[]` | Cookie prefix set on the Google Analytics 4 cookies using the `cookie_prefix` option of the gtag.js tracker. | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md index 364d515efb..cb2e83eafb 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md @@ -108,7 +108,7 @@ trackPageView({ -Every tracked event payload has a unique `event_id` UUID string set by the tracker, a set of timestamps, and other ubiquitous properties such as the `namespace`. You can find out more about how events and entities are structured [here](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +Every tracked event payload has a unique `event_id` UUID string set by the tracker, a set of timestamps, and other ubiquitous properties such as the `namespace`. You can find out more about how events and entities are structured [here](/docs/events/index.md). ## Auto-tracked entities @@ -211,13 +211,13 @@ Set the application ID using the `appId` field of the [tracker configuration o The option to track the application version was introduced in version 4.1 of the JavaScript tracker. ::: -Set the application ID using the `appVersion` field of the [tracker configuration object](/docs/sources/trackers/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md). This will be attached to every event the tracker fires using the [application context entity](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/app-information/index.md#application-context-entity-on-web-apps). +Set the application ID using the `appVersion` field of the [tracker configuration object](/docs/sources/trackers/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md). This will be attached to every event the tracker fires using the [application context entity](/docs/events/ootb-data/app-information/index.md#application-context-entity-on-web-apps). The version of can be a semver-like structure (e.g 1.1.0) or a Git commit SHA hash. ### Setting application platform -Set the application platform using the `platform` field of the [tracker configuration object](/docs/sources/trackers/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md). This will be attached to every event the tracker fires. Its default value is “web”. For a list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters). +Set the application platform using the `platform` field of the [tracker configuration object](/docs/sources/trackers/javascript-trackers/web-tracker/tracker-setup/initialization-options/index.md). This will be attached to every event the tracker fires. Its default value is “web”. For a list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md#application-parameters). ### Setting the user ID diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/link-click/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/link-click/index.md index fb9e8fe6ca..7302a60710 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/link-click/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/link-click/index.md @@ -22,13 +22,13 @@ Link click events are **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/optimizely/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/optimizely/index.md index cbb54ce0f1..26ac527bb0 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/optimizely/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/optimizely/index.md @@ -21,13 +21,13 @@ You can have a look at the JsonSchema [here](https://github.com/snowplow/iglu-ce | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ❌ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/privacy-sandbox/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/privacy-sandbox/index.md index f6ffd6df29..6596b52ae9 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/privacy-sandbox/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/privacy-sandbox/index.md @@ -30,18 +30,18 @@ The Privacy Sandbox context entity is **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ❌ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-privacy-sandbox@latest/dist/index.umd.min.js", ["snowplowPrivacySandbox", "PrivacySandboxPlugin"] ); @@ -58,8 +58,8 @@ window.snowplow('addPlugin', import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { PrivacySandboxPlugin } from '@snowplow/browser-plugin-privacy-sandbox'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ PrivacySandboxPlugin() ], }); ``` diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/screen-views/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/screen-views/index.md index 7ce699d6be..7df629c27e 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/screen-views/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/screen-views/index.md @@ -98,7 +98,7 @@ newTracker('sp1', '{{collector_url}}', { ## Track a screen view event To track a screen view event, use the `trackScreenView` function. -This will track a self-describing event with [the schema described here](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-and-screen-view-events/index.md#screen-view-events). +This will track a self-describing event with [the schema described here](/docs/events/ootb-data/page-and-screen-view-events/index.md#screen-view-events). @@ -221,11 +221,11 @@ Concretely, it consists of the following metrics: 3. Number of list items scrolled out of all list items (requires some manual tracking). 4. Scroll depth in pixels (requires some manual tracking). -This information is attached using a [`screen_summary` context entity](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md#screen-summary-entity) to the following events: +This information is attached using a [`screen_summary` context entity](/docs/events/ootb-data/page-activity-tracking/index.md#screen-summary-entity) to the following events: -1. [`screen_end` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md#screen-end-event) that is automatically tracked before a new screen view event. -2. [`application_background` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#background-event). -3. [`application_foreground` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#foreground-event). +1. [`screen_end` event](/docs/events/ootb-data/page-activity-tracking/index.md#screen-end-event) that is automatically tracked before a new screen view event. +2. [`application_background` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#background-event). +3. [`application_foreground` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#foreground-event). Screen engagement tracking is enabled by default, but can be configured using the `screenEngagementAutotracking` option when initializing the plugin. diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/site-search/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/site-search/index.md index 231e4a77e7..11686eaf64 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/site-search/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/site-search/index.md @@ -20,18 +20,18 @@ Site search events must be **manually tracked**. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-site-tracking@latest/dist/index.umd.min.js", ["snowplowSiteTracking", "SiteTrackingPlugin"] ); @@ -48,8 +48,8 @@ window.snowplow('addPlugin', import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { SiteTrackingPlugin, trackSiteSearch } from '@snowplow/browser-plugin-site-tracking'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ SiteTrackingPlugin() ], }); ``` @@ -62,7 +62,7 @@ newTracker('sp1', '{{collector_url}}', { Use the `trackSiteSearch` method to track users searching your website. Here are its arguments: | **Name** | **Required?** | **Description** | **Type** | -|----------------|---------------|---------------------------------|----------| +| -------------- | ------------- | ------------------------------- | -------- | | `terms` | Yes | Search terms | array | | `filters` | No | Search filters | JSON | | `totalResults` | No | Results found | number | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/social-media/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/social-media/index.md index 2740a6fad3..7ea392ef16 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/social-media/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/social-media/index.md @@ -20,18 +20,18 @@ Social media interaction events must be **manually tracked**. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-site-tracking@latest/dist/index.umd.min.js", ["snowplowSiteTracking", "SiteTrackingPlugin"] ); @@ -48,8 +48,8 @@ window.snowplow('addPlugin', import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { SiteTrackingPlugin, trackSiteSearch } from '@snowplow/browser-plugin-site-tracking'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ SiteTrackingPlugin() ], }); ``` @@ -64,7 +64,7 @@ Social tracking is used to track the way users interact with Facebook, Twitter a The `trackSocialInteraction` method takes three parameters: | **Parameter** | **Description** | **Required?** | **Example value** | -|---------------|---------------------------------------------------------------|---------------|-----------------------| +| ------------- | ------------------------------------------------------------- | ------------- | --------------------- | | `action` | Social action performed | Yes | 'like', 'retweet' | | `network` | Social network | Yes | 'facebook', 'twitter' | | `target` | Object social action is performed on e.g. page ID, product ID | No | '19.99' | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/timezone-geolocation/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/timezone-geolocation/index.md index 40b2bd0197..37117db642 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/timezone-geolocation/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/timezone-geolocation/index.md @@ -24,18 +24,18 @@ The timezone property is **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ❌ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-timezone@latest/dist/index.umd.min.js", ["snowplowTimezone", "TimezonePlugin"] ); @@ -52,8 +52,8 @@ window.snowplow('addPlugin', import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { TimezonePlugin } from '@snowplow/browser-plugin-timezone'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ TimezonePlugin() ], }); ``` @@ -78,18 +78,18 @@ Geolocation context entities are **automatically tracked** once configured. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-geolocation@latest/dist/index.umd.min.js", ["snowplowGeolocation", "GeolocationtPlugin"], [false] // Enable at load @@ -101,14 +101,14 @@ window.snowplow('addPlugin', - `npm install @snowplow/browser-plugin-geolocation` - `yarn add @snowplow/browser-plugin-geolocation` -- `pnpm add @snowplow/browser-plugin-geolocation` +- `pnpm add @snowplow/browser-plugin-geolocation` ```javascript import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { GeolocationPlugin, enableGeolocationContext } from '@snowplow/browser-plugin-geolocation'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ GeolocationPlugin() ], }); diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/timings/generic/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/timings/generic/index.md index cbdbcb637d..bd35eaed7d 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/timings/generic/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/timings/generic/index.md @@ -20,18 +20,18 @@ Timing events must be **manually tracked**. | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-site-tracking@latest/dist/index.umd.min.js", ["snowplowSiteTracking", "SiteTrackingPlugin"] ); @@ -48,8 +48,8 @@ window.snowplow('addPlugin', import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { SiteTrackingPlugin, trackSiteSearch } from '@snowplow/browser-plugin-site-tracking'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ SiteTrackingPlugin() ], }); ``` @@ -63,7 +63,7 @@ newTracker('sp1', '{{collector_url}}', { Use the `trackTiming` method to track how long something took. Here are its arguments: | **Name** | **Required?** | **Description** | **Type** | -|------------|---------------|--------------------------------|----------| +| ---------- | ------------- | ------------------------------ | -------- | | `category` | Yes | Timing category | string | | `variable` | Yes | Timed variable | string | | `timing` | Yes | Number of milliseconds elapsed | number | diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/timings/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/timings/index.md index 6ffeb8e72d..9fb23661b2 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/timings/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/timings/index.md @@ -10,7 +10,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; ``` -To add performance timing context entities to your Snowplow tracking, use this Performance navigation timing plugin. +To add performance timing context entities to your Snowplow tracking, use this Performance navigation timing plugin. By default all its metrics are relative to the page load rather than absolute time stamps, making it easy to analyze and aggregate. To learn more about the properties tracked, you can visit the [specification](https://www.w3.org/TR/navigation-timing-2/) or MDN [documentation site](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming). @@ -36,18 +36,18 @@ You can also create and track general timing events using the [site tracking plu | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ❌ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-performance-navigation-timing@latest/dist/index.umd.min.js", ["snowplowPerformanceNavigationTiming", "PerformanceNavigationTimingPlugin"] ); @@ -64,8 +64,8 @@ window.snowplow('addPlugin', import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { PerformanceNavigationTimingPlugin } from '@snowplow/browser-plugin-performance-navigation-timing'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ PerformanceNavigationTimingPlugin() ], }); ``` @@ -75,7 +75,7 @@ newTracker('sp1', '{{collector_url}}', { ## More detailed analysis for Single Page Applications (SPA) -As these metrics are primarily related to the initial page serve and load, after the window.onload handler ends the metrics will likely stay static for the life of the SPA page. If there's a pattern to the API requests the SPA makes for new content, the [PerformanceObserver](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver) could be used to capture the network metrics for that request from the performance API and re-use the schema. +As these metrics are primarily related to the initial page serve and load, after the window.onload handler ends the metrics will likely stay static for the life of the SPA page. If there's a pattern to the API requests the SPA makes for new content, the [PerformanceObserver](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver) could be used to capture the network metrics for that request from the performance API and re-use the schema. For actual rendering performance, the application will have to use the PerformanceMark/PerformanceMeasure [User timing](https://developer.mozilla.org/en-US/docs/Web/API/Performance_API/User_timing) APIs. These allow custom timing milestones, but since it's completely custom and there are no common conventions for using these APIs, currently there is no automatic support in the tracker for tracking these. Therefore we encourage you to build your custom schema in case you believe you would benefit from these additional metrics. @@ -121,18 +121,18 @@ Performance timing context entities are **automatically tracked** once configure | Tracker Distribution | Included | -|----------------------|----------| +| -------------------- | -------- | | `sp.js` | ✅ | | `sp.lite.js` | ❌ | **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
**Note:** The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production. ```javascript -window.snowplow('addPlugin', +window.snowplow('addPlugin', "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-performance-timing@latest/dist/index.umd.min.js", ["snowplowPerformanceTiming", "PerformanceTimingPlugin"] ); @@ -149,8 +149,8 @@ window.snowplow('addPlugin', import { newTracker, trackPageView } from '@snowplow/browser-tracker'; import { PerformanceTimingPlugin } from '@snowplow/browser-plugin-performance-timing'; -newTracker('sp1', '{{collector_url}}', { - appId: 'my-app-id', +newTracker('sp1', '{{collector_url}}', { + appId: 'my-app-id', plugins: [ PerformanceTimingPlugin() ], }); ``` diff --git a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/webview/index.md b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/webview/index.md index d56fd0da2f..48bf801147 100644 --- a/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/webview/index.md +++ b/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/webview/index.md @@ -10,11 +10,11 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; ``` -This plugin provides integration for hybrid apps using the Snowplow native mobile ([Android and iOS v6.1+](/docs/sources/trackers/mobile-trackers/hybrid-apps/index.md)) or [React Native v4.2+](docs/sources/trackers/react-native-tracker/hybrid-apps/index.md) trackers. Hybrid apps are mobile apps that in addition to a native interface, provide part of the UI through an embedded Web view. +This plugin provides integration for hybrid apps using the Snowplow native mobile ([Android and iOS v6.1+](/docs/sources/trackers/mobile-trackers/hybrid-apps/index.md)) or [React Native v4.2+](docs/sources/trackers/react-native-tracker/hybrid-apps/index.md) trackers. Hybrid apps are mobile apps that in addition to a native interface, provide part of the UI through an embedded web view. -If your webapp will run both separately and as part of a hybrid app, with this plugin you only need one tracking implementation for your webapp (you still have to implement the mobile trackers too). +If your web app will run both separately and as part of a hybrid app, with this plugin you only need one tracking implementation for your web app. You still have to implement the mobile trackers too. -When the plugin is active, for every event the web tracker checks if it is running in a WebView with at least one of the mobile interfaces available. If it is, the event is forwarded to the mobile tracker, and not tracked by the web tracker. If not, the event is tracked as normal. +When the plugin is active, for every event the web tracker checks if it's running in a web view with at least one of the mobile interfaces available. If it is, the web tracker forwards the event to the mobile tracker, and doesn't track it itself. If not, the web tracker tracks the event as normal. :::note The plugin is available since version 4.3 of the tracker. @@ -63,21 +63,21 @@ The supported trackers are: How to set up hybrid app tracking: 1. Implement the Snowplow [iOS, Android](/docs/sources/trackers/mobile-trackers/index.md), or [React Native](docs/sources/trackers/react-native-tracker/index.md) tracker in your mobile codebase. -2. Create a WebView based on your web app, with Snowplow Web tracking and WebView plugin instrumented. -3. Subscribe to the WebView. Read how to do this for [native mobile](/docs/sources/trackers/mobile-trackers/hybrid-apps/index.md) or [React Native](docs/sources/trackers/react-native-tracker/hybrid-apps/index.md). +2. Create a web view based on your web app, with Snowplow web tracking and WebView plugin instrumented. +3. Subscribe to the web view. Read how to do this for [native mobile](/docs/sources/trackers/mobile-trackers/hybrid-apps/index.md) or [React Native](docs/sources/trackers/react-native-tracker/hybrid-apps/index.md). 4. Track events from web and mobile. This plugin uses the [Snowplow WebView tracker](/docs/sources/trackers/webview-tracker/index.md) as a dependency. ## What do the forwarded events look like? -The forwarded hybrid events will have all the information tracked by the web tracker. This includes all context entities, whether configured by the tracker [automatically](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md#auto-tracked-entities) or by you as a global context. Baked-in (non-entity) properties such as useragent or URL are also included. +The forwarded hybrid events will have all the information tracked by the web tracker. This includes all entities, whether configured by the tracker [automatically](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/index.md#auto-tracked-entities) or by you as a global context. Baked-in (non-entity) properties such as user agent or URL are also included. -Additionally, any configured mobile context entities will also be added. Again, this includes [autotracked entities](/docs/sources/trackers/mobile-trackers/tracking-events/index.md#auto-tracked-events-and-entities) such as the screen, session, or platform entities, as well as any global context entities. +Additionally, any configured mobile entities will also be added. Again, this includes [auto-tracked entities](/docs/sources/trackers/mobile-trackers/tracking-events/index.md#auto-tracked-events-and-entities) such as the screen, session, or platform entities, as well as any global context entities. -The forwarded events will have the web tracker version, e.g. "js-4.3.0", but the namespace and appId from the mobile tracker. +The forwarded events will have the web tracker version, e.g. "js-4.3.0", but the `namespace` and `appId` from the mobile tracker. -Hybrid events are still compatible with our [Unified Digital dbt model](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-unified-data-model/index.md). +Hybrid events are still compatible with the Snowplow [Unified Digital dbt model](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-unified-data-model/index.md). ## Install plugin @@ -91,7 +91,7 @@ Hybrid events are still compatible with our [Unified Digital dbt model](/docs/mo **Download:** -
Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
+
Download from GitHub Releases (Recommended)GitHub Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)
```javascript window.snowplow( @@ -157,6 +157,6 @@ newTracker('sp1', '{{collector_url}}', { -:::warning Take care when specifying namespaces -If there is no mobile tracker with the specified namespace(s), the event will not be tracked. +:::warning Specifying namespaces +When a mobile interface is available, the web tracker will forward the event rather than tracking it. If you specify namespaces in the configuration, and no mobile trackers actually exist with those namespaces, the event will be lost. ::: diff --git a/docs/sources/trackers/lua-tracker/tracking-specific-events/index.md b/docs/sources/trackers/lua-tracker/tracking-specific-events/index.md index 7cc6eaf6f3..8b9fc233e5 100644 --- a/docs/sources/trackers/lua-tracker/tracking-specific-events/index.md +++ b/docs/sources/trackers/lua-tracker/tracking-specific-events/index.md @@ -95,6 +95,6 @@ local ok, err = tracker:track_screen_view("Character Configuration - Part 1", "c ## Adding user and platform data -The tracker can store information about the user associated with the event, such as their `user_id`, what type of device they used, or what size screen that device had. It also stores which platform the event occurred on – e.g. server-side app, mobile, games console, etc. This is done through the provided `set_*` methods available on a tracker instance. The stored information is attached to the tracked events using fields described in the [Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +The tracker can store information about the user associated with the event, such as their `user_id`, what type of device they used, or what size screen that device had. It also stores which platform the event occurred on – e.g. server-side app, mobile, games console, etc. This is done through the provided `set_*` methods available on a tracker instance. The stored information is attached to the tracked events using fields described in the [Tracker Protocol](/docs/events/index.md). For a full list of setters, check out the [Tracker API Documentation](https://snowplow.github.io/snowplow-lua-tracker/modules/Tracker.html). diff --git a/docs/sources/trackers/mobile-trackers/client-side-properties/index.md b/docs/sources/trackers/mobile-trackers/client-side-properties/index.md index 0d51211455..3dbef2d4bf 100644 --- a/docs/sources/trackers/mobile-trackers/client-side-properties/index.md +++ b/docs/sources/trackers/mobile-trackers/client-side-properties/index.md @@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem'; An event describes a single, transient activity. The context in which that event occurs - the relatively persistent environment - is also incredibly valuable data. -The tracker allows the addition of a persistent set of information through the `SubjectConfiguration`, which represents the basic information about the user and the app. This data is added to every event as part of the [canonical event properties](/docs/sources/trackers/snowplow-tracker-protocol/going-deeper/event-parameters/index.md). +The tracker allows the addition of a persistent set of information through the `SubjectConfiguration`, which represents the basic information about the user and the app. This data is added to every event as part of the [canonical event properties](/docs/events/going-deeper/event-parameters/index.md). | Property | Description | Automatically added? | Column(s) in enriched event | | -------- | ----------- |: --------------------- :| ----------------------------------- | diff --git a/docs/sources/trackers/mobile-trackers/hybrid-apps/index.md b/docs/sources/trackers/mobile-trackers/hybrid-apps/index.md index ee583230d7..0ba6c4c385 100644 --- a/docs/sources/trackers/mobile-trackers/hybrid-apps/index.md +++ b/docs/sources/trackers/mobile-trackers/hybrid-apps/index.md @@ -56,7 +56,7 @@ We recommend using the Web tracker (v4.3+) to forward all Web events to the mobi 4. Track events as usual. -The Web tracker will automatically intercept all web events and forward them to the mobile tracker. The forwarded events will have the tracker version from Web, e.g. "js-4.1.0", but will otherwise be tracked like the mobile events. They may contain additional information not present in the native mobile events, such as a browser useragent string or URL, or Web context entities e.g. the [WebPage entity](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/page-views/#webpage-page-view-id-context-entity). +The Web tracker will automatically intercept all web events and forward them to the mobile tracker. The forwarded events will have the tracker version from Web, e.g. "js-4.1.0", but will otherwise be tracked like the mobile events. They may contain additional information not present in the native mobile events, such as a browser useragent string or URL, or Web context entities e.g. the [WebPage entity](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/page-views/index.md#webpage-page-view-id-context-entity). The forwarded events are filtered out of the Web tracker event queue so that they are not tracked twice. diff --git a/docs/sources/trackers/mobile-trackers/migration-guides/migration-guide-to-new-ecommerce/index.md b/docs/sources/trackers/mobile-trackers/migration-guides/migration-guide-to-new-ecommerce/index.md index d2ce797852..586bd771a7 100644 --- a/docs/sources/trackers/mobile-trackers/migration-guides/migration-guide-to-new-ecommerce/index.md +++ b/docs/sources/trackers/mobile-trackers/migration-guides/migration-guide-to-new-ecommerce/index.md @@ -184,7 +184,7 @@ Note that address details and affiliation are not captured in `TransactionEvent` ### Old events Using the old event types, an event is generated for each `EcommerceTransaction` event as well as each `EcommerceTransactionItem` attached. Therefore, tracking an `EcommerceTransaction` event with 3 items would result in 4 events being tracked. These events are not linked at all, unless the same `orderId` is provided to all the objects, adding potential challenges in data modeling. -In the tracked data, the events have `event_name` `transaction` or `transaction_item`. The data is sent within the legacy event properties `tr_x` and `ti_x`, e.g. `tr_id` for the `EcommerceTransaction` `orderId` property. All of these properties are listed [here](/docs/sources/trackers/snowplow-tracker-protocol/index.md). Each one maps to a column in the warehouse table. +In the tracked data, the events have `event_name` `transaction` or `transaction_item`. The data is sent within the legacy event properties `tr_x` and `ti_x`, e.g. `tr_id` for the `EcommerceTransaction` `orderId` property. All of these properties are listed [here](/docs/events/index.md). Each one maps to a column in the warehouse table. ### New events The new Ecommerce event types take advantage of the Snowplow entities/event context feature. Tracking `TransactionEvent` with 3 items results in a single event being tracked. The items, and the details of the transaction, are attached as entities. That single event would have one `TransactionEntity`, three `ProductEntity`, plus whichever out-of-the-box and/or custom entities are configured. diff --git a/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-1-0-java-0-5-0/index.md b/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-1-0-java-0-5-0/index.md index ee602e3ef7..a1ea80b500 100644 --- a/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-1-0-java-0-5-0/index.md +++ b/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-1-0-java-0-5-0/index.md @@ -119,7 +119,7 @@ You can change the platform the subject is using by calling: s1.setPlatform("cnsl"); ``` -For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md). ### 3.2 Set user ID with `setUserId` diff --git a/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-2-0-java-0-6-0/index.md b/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-2-0-java-0-6-0/index.md index eea4ba5152..bbc7f3b2c2 100644 --- a/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-2-0-java-0-6-0/index.md +++ b/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-2-0-java-0-6-0/index.md @@ -88,7 +88,7 @@ You can change the platform by calling: tracker.setPlatform("cnsl"); ``` -For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md). ## 3. Adding extra data: the Subject class diff --git a/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-3-0/index.md b/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-3-0/index.md index ea5e9ad316..8e6fdf4486 100644 --- a/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-3-0/index.md +++ b/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-3-0/index.md @@ -117,7 +117,7 @@ tracker.setPlatform(DevicePlatforms.{{ Valid Enum Option }}) There are several different DevicePlatforms options to choose from. -For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md). #### 2.3.8 Change the tracker's subject with `setSubject` diff --git a/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-4-0/index.md b/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-4-0/index.md index 2fe81fb01e..246aba7beb 100644 --- a/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-4-0/index.md +++ b/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-4-0/index.md @@ -124,7 +124,7 @@ tracker.setPlatform(DevicePlatforms.{{ Valid Enum Option }}) There are several different DevicePlatforms options to choose from. -For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md). #### 2.3.8 Change the tracker's subject with `setSubject` diff --git a/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-5-0/index.md b/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-5-0/index.md index 8804ea3918..4e5709377a 100644 --- a/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-5-0/index.md +++ b/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-5-0/index.md @@ -226,7 +226,7 @@ tracker.setPlatform(DevicePlatforms.{{ Valid Enum Option }}) There are several different DevicePlatforms options to choose from. -For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md). #### 2.3.13 Change the tracker's subject with `setSubject` diff --git a/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-6-0/index.md b/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-6-0/index.md index 5ee8514d0a..b9e1484bd4 100644 --- a/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-6-0/index.md +++ b/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-6-0/index.md @@ -249,7 +249,7 @@ tracker.setPlatform(DevicePlatforms.{{ Valid Enum Option }}) There are several different DevicePlatforms options to choose from. -For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md). #### 2.3.13 Change the tracker's subject with `setSubject` diff --git a/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-7-0/index.md b/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-7-0/index.md index ad96adf49e..e496dac6cf 100644 --- a/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-7-0/index.md +++ b/docs/sources/trackers/mobile-trackers/previous-versions/android-tracker/android-0-7-0/index.md @@ -240,7 +240,7 @@ tracker.setPlatform(DevicePlatforms.{{ Valid Enum Option }}) There are several different DevicePlatforms options to choose from. -For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md). #### 2.3.13 Change the tracker's subject with `setSubject` diff --git a/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-4-0/index.md b/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-4-0/index.md index 8e5d810c8c..0315e7b12c 100644 --- a/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-4-0/index.md +++ b/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-4-0/index.md @@ -279,7 +279,7 @@ On the tracker setup you can override the device platform entry calling: It resets the parameter `p` (platform) to the new value. -[Here](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters) a full list of the supported platform values. +[Here](/docs/events/index.md#application-parameters) a full list of the supported platform values. ### Sending events diff --git a/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-5-0/index.md b/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-5-0/index.md index a8de6c4bea..78057a9613 100644 --- a/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-5-0/index.md +++ b/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-5-0/index.md @@ -279,7 +279,7 @@ On the tracker setup you can override the device platform entry calling: It resets the parameter `p` (platform) to the new value. -[Here](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters) a full list of the supported platform values. +[Here](/docs/events/index.md#application-parameters) a full list of the supported platform values. ### Sending events diff --git a/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-6-0/index.md b/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-6-0/index.md index 5fdfbdc25a..a38cabdeb1 100644 --- a/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-6-0/index.md +++ b/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-6-0/index.md @@ -279,7 +279,7 @@ On the tracker setup you can override the device platform entry calling: It resets the parameter `p` (platform) to the new value. -[Here](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters) a full list of the supported platform values. +[Here](/docs/events/index.md#application-parameters) a full list of the supported platform values. ### Sending events diff --git a/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-7-0/index.md b/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-7-0/index.md index 534feb420e..b5d07a3db4 100644 --- a/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-7-0/index.md +++ b/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker-1-7-0/index.md @@ -279,7 +279,7 @@ On the tracker setup you can override the device platform entry calling: It resets the parameter `p` (platform) to the new value. -[Here](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters) a full list of the supported platform values. +[Here](/docs/events/index.md#application-parameters) a full list of the supported platform values. ### Sending events diff --git a/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker/index.md b/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker/index.md index 30f9977618..8841f1e1e5 100644 --- a/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker/index.md +++ b/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/ios-tracker/index.md @@ -275,7 +275,7 @@ On the tracker setup you can override the device platform entry calling: It resets the parameter `p` (platform) to the new value. -[Here](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters) a full list of the supported platform values. +[Here](/docs/events/index.md#application-parameters) a full list of the supported platform values. ### Sending events diff --git a/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/objective-c-0-9-0/index.md b/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/objective-c-0-9-0/index.md index 9c55c93637..4c62b5a892 100644 --- a/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/objective-c-0-9-0/index.md +++ b/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/objective-c-0-9-0/index.md @@ -358,7 +358,7 @@ On the tracker setup you can override the device platform entry calling: It resets the parameter `p` (platform) to the new value. -[Here](/docs/sources/trackers/snowplow-tracker-protocol/index.md) a full list of the supported platform values. +[Here](/docs/events/index.md) a full list of the supported platform values. ### Sending events diff --git a/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/objective-c-1-2-0/index.md b/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/objective-c-1-2-0/index.md index b913ed16f5..c94393be33 100644 --- a/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/objective-c-1-2-0/index.md +++ b/docs/sources/trackers/mobile-trackers/previous-versions/objective-c-tracker/objective-c-1-2-0/index.md @@ -256,7 +256,7 @@ On the tracker setup you can override the device platform entry calling: It resets the parameter `p` (platform) to the new value. -[Here](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters) a full list of the supported platform values. +[Here](/docs/events/index.md#application-parameters) a full list of the supported platform values. ### Sending events diff --git a/docs/sources/trackers/mobile-trackers/tracking-events/index.md b/docs/sources/trackers/mobile-trackers/tracking-events/index.md index 986b41cf5f..ce439eea63 100644 --- a/docs/sources/trackers/mobile-trackers/tracking-events/index.md +++ b/docs/sources/trackers/mobile-trackers/tracking-events/index.md @@ -60,7 +60,7 @@ The tracker makes it easy to track different kinds of data. We provide a range o Each event has an associated context, which is composed of entities. The tracker attaches entities to the events based on the configuration, but you can attach your own [custom entities](/docs/sources/trackers/mobile-trackers/custom-tracking-using-schemas/index.md) as well. -Every tracked event payload has a unique `event_id` UUID string set by the tracker, a set of timestamps, and other ubiquitous properties such as the `namespace`. The `event_id` is returned from the `tracker.track(event)` method. You can know more about how events and entities are structured [here](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +Every tracked event payload has a unique `event_id` UUID string set by the tracker, a set of timestamps, and other ubiquitous properties such as the `namespace`. The `event_id` is returned from the `tracker.track(event)` method. You can know more about how events and entities are structured [here](/docs/events/index.md). See the full configuration and parameter options for all these classes and methods in the API docs - [Android](https://snowplow.github.io/snowplow-android-tracker/index.html) and [iOS](https://snowplow.github.io/snowplow-ios-tracker/documentation/snowplowtracker/). diff --git a/docs/sources/trackers/mobile-trackers/tracking-events/lifecycle-tracking/index.md b/docs/sources/trackers/mobile-trackers/tracking-events/lifecycle-tracking/index.md index 38961f0f35..1c9862a03e 100644 --- a/docs/sources/trackers/mobile-trackers/tracking-events/lifecycle-tracking/index.md +++ b/docs/sources/trackers/mobile-trackers/tracking-events/lifecycle-tracking/index.md @@ -41,8 +41,8 @@ TrackerConfiguration trackerConfig = new TrackerConfiguration("appId") -Once enabled, the tracker will automatically track a [`Background` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#background-event) when the app is moved to background and a [`Foreground` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#foreground-event) when the app moves back to foreground (becomes visible in the screen). +Once enabled, the tracker will automatically track a [`Background` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#background-event) when the app is moved to background and a [`Foreground` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#foreground-event) when the app moves back to foreground (becomes visible in the screen). -The tracker attaches a [`LifecycleEntity`](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#lifecycle-context-entity) to all the events tracked by the tracker reporting if the app was visible (foreground state) when the event was tracked. +The tracker attaches a [`LifecycleEntity`](/docs/events/ootb-data/mobile-lifecycle-events/index.md#lifecycle-context-entity) to all the events tracked by the tracker reporting if the app was visible (foreground state) when the event was tracked. The `LifecycleEntity` value is conditioned by the internal state of the tracker only. To make an example, if the app is in foreground state but the developer tracks a `Background` event intentionally, it would force the generation of a `LifecycleEntity` that mark the app as non visible, even if it's actually visible in the device. diff --git a/docs/sources/trackers/mobile-trackers/tracking-events/platform-and-application-context/index.md b/docs/sources/trackers/mobile-trackers/tracking-events/platform-and-application-context/index.md index 1d04d8710b..0fd8a4d066 100644 --- a/docs/sources/trackers/mobile-trackers/tracking-events/platform-and-application-context/index.md +++ b/docs/sources/trackers/mobile-trackers/tracking-events/platform-and-application-context/index.md @@ -86,7 +86,7 @@ The [platform context entity](https://github.com/snowplow/iglu-central/blob/mast | `appSetIdScope` | String (either "app" or "developer") | ✅ | ❌ | Scope of the `appSetId`. Can be scoped to the app or to a developer account on an app store (all apps from the same developer on the same device will have the same ID) | No | :::note Android screen resolution -The screen resolution for the platform entity is obtained from the Android context resources. The height value will likely be lower than that reported in the canonical `dvce_screenheight` [event property](/docs/sources/trackers/snowplow-tracker-protocol/going-deeper/event-parameters/index.md), which is fetched from `WindowManager`, an older API that still includes the menu bar. +The screen resolution for the platform entity is obtained from the Android context resources. The height value will likely be lower than that reported in the canonical `dvce_screenheight` [event property](/docs/events/going-deeper/event-parameters/index.md), which is fetched from `WindowManager`, an older API that still includes the menu bar. To standardize the screen resolution between event and entity properties, provide a `SubjectConfiguration` with `useContextResourcesScreenResolution(true)` flag at tracker initialization. This flag is false by default, and available from Android tracker v6.0.3 onwards. Read about configuring `Subject` properties [here](/docs/sources/trackers/mobile-trackers/client-side-properties/index.md). ::: diff --git a/docs/sources/trackers/mobile-trackers/tracking-events/screen-tracking/index.md b/docs/sources/trackers/mobile-trackers/tracking-events/screen-tracking/index.md index 9f53a08b57..e1e4e0805b 100644 --- a/docs/sources/trackers/mobile-trackers/tracking-events/screen-tracking/index.md +++ b/docs/sources/trackers/mobile-trackers/tracking-events/screen-tracking/index.md @@ -127,8 +127,8 @@ Using the Android `Application.ActivityLifecycleCallbacks` interface, the tracke Automatic screen view tracking tracks two pieces of information: -- The tracker automatically tracks each screen change using a [`ScreenView` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-and-screen-view-events/index.md#screen-view-events). -- If the `TrackerConfiguration.screenContext` property is enabled, the tracker attaches a [`Screen` entity](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-and-screen-view-events/index.md#screen-view-events) to all the events tracked by the tracker reporting the last (and probably current) screen visible on device when the event was tracked. +- The tracker automatically tracks each screen change using a [`ScreenView` event](/docs/events/ootb-data/page-and-screen-view-events/index.md#screen-view-events). +- If the `TrackerConfiguration.screenContext` property is enabled, the tracker attaches a [`Screen` entity](/docs/events/ootb-data/page-and-screen-view-events/index.md#screen-view-events) to all the events tracked by the tracker reporting the last (and probably current) screen visible on device when the event was tracked. The `Screen` entity is conditioned by the internal state of the tracker only. To make an example, if the developer manually tracks a `ScreenView` event, all the following events will have a `Screen` entity attached reporting the same information as the last tracked ScreenView event, even if it was manually tracked and the app is in a different screen. @@ -150,11 +150,11 @@ Concretely, it consists of the following metrics: 3. Number of list items scrolled out of all list items (requires some manual tracking). 4. Scroll depth in pixels (requires some manual tracking). -This information is attached using a [`screen_summary` context entity](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md#screen-summary-entity) to the following events: +This information is attached using a [`screen_summary` context entity](/docs/events/ootb-data/page-activity-tracking/index.md#screen-summary-entity) to the following events: -1. [`screen_end` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md#screen-end-event) that is automatically tracked before a new screen view event. -2. [`application_background` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#background-event). -3. [`application_foreground` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#foreground-event). +1. [`screen_end` event](/docs/events/ootb-data/page-activity-tracking/index.md#screen-end-event) that is automatically tracked before a new screen view event. +2. [`application_background` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#background-event). +3. [`application_foreground` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#foreground-event). Screen engagement tracking is enabled by default, but can be configured using the `TrackerConfiguration.screenEngagementAutotracking` option. diff --git a/docs/sources/trackers/mobile-trackers/tracking-events/session-tracking/index.md b/docs/sources/trackers/mobile-trackers/tracking-events/session-tracking/index.md index bf6b9eb157..3aecdd862e 100644 --- a/docs/sources/trackers/mobile-trackers/tracking-events/session-tracking/index.md +++ b/docs/sources/trackers/mobile-trackers/tracking-events/session-tracking/index.md @@ -43,7 +43,7 @@ TrackerConfiguration trackerConfig = new TrackerConfiguration("appId") When enabled, the tracker appends a [`client_session` entity](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/client_session/jsonschema/1-0-2) to each event it sends and it maintains this session information as long as the application is installed on the device. -Sessions correspond to tracked user activity. User information is set via the [Client session context entity](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/user-and-session-identification/index.md#client-session-context-entity). +Sessions correspond to tracked user activity. User information is set via the [Client session context entity](/docs/events/ootb-data/user-and-session-identification/index.md#client-session-context-entity). A session expires when no tracking events have occurred for the amount of time defined in a timeout (by default 30 minutes). The session timeout check is executed for each event tracked. If the gap between two consecutive events is longer than the timeout the session is renewed. There are two timeouts since a session can timeout in the foreground (while the app is visible) or in the background (when the app has been suspended, but not closed). diff --git a/docs/sources/trackers/mobile-trackers/tracking-events/visionos/index.md b/docs/sources/trackers/mobile-trackers/tracking-events/visionos/index.md index d659c55407..6ba9f03c80 100644 --- a/docs/sources/trackers/mobile-trackers/tracking-events/visionos/index.md +++ b/docs/sources/trackers/mobile-trackers/tracking-events/visionos/index.md @@ -18,7 +18,7 @@ The Snowplow iOS tracker supports tracking within visionOS apps. All the usual e The immersive space context entity is semi-automatically added to all events. -The events are: `OpenWindowEvent`, `DismissWindowEvent`, `OpenImmersiveSpaceEvent`, and `DismissImmersiveSpaceEvent`. Find the schema details for the events and entities [here](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/visionos-swiftui/index.md). +The events are: `OpenWindowEvent`, `DismissWindowEvent`, `OpenImmersiveSpaceEvent`, and `DismissImmersiveSpaceEvent`. Find the schema details for the events and entities [here](/docs/events/ootb-data/visionos-swiftui/index.md). ### Window events diff --git a/docs/sources/trackers/php-tracker/emitters/index.md b/docs/sources/trackers/php-tracker/emitters/index.md index 52a768bb05..1424b58384 100644 --- a/docs/sources/trackers/php-tracker/emitters/index.md +++ b/docs/sources/trackers/php-tracker/emitters/index.md @@ -4,12 +4,12 @@ date: "2020-02-26" sidebar_position: 40 --- -We currently support four different emitters: sync, socket, curl and an out-of-band file emitter. The most basic emitter only requires you to select the type of emitter to be used and specify the collector's hostname as parameters. +We currently support four different emitters: sync, socket, curl, and an out-of-band file emitter. The most basic emitter only requires you to select the type of emitter to be used and specify the Collector's hostname as parameters. -All emitters support both `GET` and `POST` as methods for sending events to Snowplow collectors. +All emitters support both `GET` and `POST` as methods for sending events to Snowplow Collectors. For the sake of performance, we recommend using `POST` as the tracker can then batch many events together into a single request. -Note that depending on your pipeline architecture, your collector may have limits on the maximum request size it will accept that could be exceeded by large batch sizes. +Note that depending on your pipeline architecture, your Collector may have limits on the maximum request size it accepts that could be exceeded by large batch sizes. It is recommended that after you have finished logging all of your events to call the following method: @@ -17,18 +17,18 @@ It is recommended that after you have finished logging all of your events to cal $tracker->flushEmitters(); ``` -This will empty the event buffers of all emitters associated with your tracker object and send any left over events. In future releases, this will be an automatic process but for now, it remains manual. +This empties the event buffers of all emitters associated with your tracker object and sends any left over events. In future releases, this may be an automatic process but for now, it remains manual. ### Sync -The Sync emitter is a very basic synchronous emitter which supports both `GET` and `POST` request types. +The Sync emitter is a basic synchronous emitter which supports both `GET` and `POST` request types. -By default, this emitter uses the Request type POST, HTTP and a buffer size of 50. +By default, this emitter uses the Request type POST, HTTP, and a buffer size of 50. As of version 0.7.0, the emitter has the capability to retry failed requests. -In case connection to the collector can't be established or the request fails with a 4xx (except for 400, 401, 403, 410, 422) or 5xx status code, the same request is retried. +In case connection to the Collector can't be established or the request fails with a 4xx (except for 400, 401, 403, 410, 422) or 5xx status code, the same request is retried. The number of times a request should be retried is configurable but defaults to 1. -There is a back-off period between subsequent retries, which starts with 100ms (configurable) and increases exponentially. +The default back-off period between subsequent retries, starts with 100 ms (configurable) and increases exponentially. Example emitter creation: @@ -36,12 +36,12 @@ Example emitter creation: $emitter = new SyncEmitter($collector_uri, "http", "POST", 50); ``` -Whilst you can force the buffer size to be greater than 1 for a GET Request; it will not yield any performance changes as we can still only send 1 event at a time. +Whilst you can force the buffer size to be greater than 1 for a GET Request; it doesn't yield any performance changes as we can still only send 1 event at a time. Constructor: ```php -public function __construct($uri, $protocol = NULL, $type = NULL, $buffer_size = NULL, $debug = false, $max_retry_attempts = NULL, $retry_backoff_ms = NULL) +public function __construct($uri, $protocol = NULL, $type = NULL, $buffer_size = NULL, $debug = false, $max_retry_attempts = NULL, $retry_backoff_ms = NULL, $server_anonymization = false) ``` Arguments: @@ -54,16 +54,17 @@ Arguments: | `$buffer_size` | Amount of events to store before flush | No | Int | | `$debug` | Whether or not to log errors | No | Boolean | | `$max_retry_attempts` | The maximum number of times to retry a request. Defaults to 1. | No | Int | -| `$retry_backoff_ms` | The number of milliseconds to backoff before retrying a request. Defaults to 100ms, increases exponentially in subsequent retries. | No | Int | +| `$retry_backoff_ms` | The number of milliseconds to backoff before retrying a request. Defaults to 100 ms, increases exponentially in subsequent retries. | No | Int | +| `$server_anonymization` | Enable Server Anonymization for sent events; IP and Network User ID information isn't associated with tracked events | No | Int | ### Socket -The Socket emitter allows for the much faster transmission of Requests to the collector by allowing us to write data directly to the HTTP socket. However, this solution is still, in essence, a synchronous process and will block the execution of the main script. +The Socket emitter allows for the much faster transmission of Requests to the Collector by allowing us to write data directly to the HTTP socket. However, this solution is still, in essence, a synchronous process and blocks the execution of the main script. As of version 0.7.0, the emitter has the capability to retry failed requests. -In case connection to the collector can't be established or the request fails with a 4xx (except for 400, 401, 403, 410, 422) or 5xx status code, the same request is retried. +In case connection to the Collector can't be established or the request fails with a 4xx (except for 400, 401, 403, 410, 422) or 5xx status code, the same request is retried. The number of times a request should be retried is configurable but defaults to 1. -There is a back-off period between subsequent retries, which starts with 100ms (configurable) and increases exponentially. +The default back-off period between subsequent retries, starts with 100 ms (configurable) and increases exponentially. Example Emitter creation: @@ -71,7 +72,7 @@ Example Emitter creation: $emitter = new SocketEmitter($collector_uri, NULL, "GET", NULL, NULL); ``` -Whilst you can force the buffer size to be greater than 1 for a GET Request; it will not yield any performance changes as we can still only send 1 event at a time. +Whilst you can force the buffer size to be greater than 1 for a GET Request; it does not yield any performance changes as we can still only send 1 event at a time. Constructor: @@ -90,16 +91,17 @@ Arguments: | `$buffer_size` | Amount of events to store before flush | No | Int | | `$debug` | Whether or not to log errors | No | Boolean | | `$max_retry_attempts` | The maximum number of times to retry a request. Defaults to 1. | No | Int | -| `$retry_backoff_ms` | The number of milliseconds to backoff before retrying a request. Defaults to 100ms, increases exponentially in subsequent retries. | No | Int | +| `$retry_backoff_ms` | The number of milliseconds to backoff before retrying a request. Defaults to 100 ms, increases exponentially in subsequent retries. | No | Int | +| `$server_anonymization` | Enable Server Anonymization for sent events; IP and Network User ID information isn't associated with tracked events | No | Int | ### Curl -The Curl Emitter allows us to have the closest thing to native asynchronous requests in PHP. The curl emitter uses the `curl_multi_init` resource which allows us to send any number of requests asynchronously. This garners quite a performance gain over the sync and socket emitters as we can now send more than one request at a time. +The Curl Emitter allows us to have the closest thing to native asynchronous requests in PHP. The curl emitter uses the `curl_multi_init` resource which allows us to send any number of requests asynchronously. This garners a performance gain over the sync and socket emitters as we can now send more than one request at a time. On top of this, we are also using a modified version of this **[Rolling Curl library](https://github.com/joshfraser/rolling-curl)** for the actual sending of the curl requests. This allows for a more efficient implementation of asynchronous curl requests as we can now have multiple requests sending at the same time, and in addition as soon as one is done a new request is started. :::note -The collector does not retry failed requests to the collector. Failed requests to the collector (e.g., due to it being not reachable) result in lost events. +The emitter doesn't retry failed requests to the Collector. Failed requests to the Collector (for example due to it being not reachable) result in lost events. ::: Example Emitter creation: @@ -108,7 +110,7 @@ Example Emitter creation: $emitter = new CurlEmitter($collector_uri, false, "GET", 2); ``` -Whilst you can force the buffer size to be greater than 1 for a GET request, it will not yield any performance changes as we can still only send 1 event at a time. +Whilst you can force the buffer size to be greater than 1 for a GET request, it doesn't yield any performance changes as we can still only send 1 event at a time. Constructor: @@ -118,16 +120,17 @@ public function __construct($uri, $protocol = NULL, $type = NULL, $buffer_size = Arguments: -| **Argument** | **Description** | **Required?** | **Validation** | -|-----------------|---------------------------------------------------------|---------------|------------------| -| `$uri` | Collector hostname | Yes | Non-empty string | -| `$protocol` | Collector Protocol (HTTP or HTTPS) | No | String | -| `$type` | Request Type (POST or GET) | No | String | -| `$buffer_size` | Amount of events to store before flush | No | Int | -| `$debug` | Whether or not to log errors | No | Boolean | -| `$curl_timeout` | Maximum time the request is allowed to take, in seconds | No | Int | +| **Argument** | **Description** | **Required?** | **Validation** | +|-------------------------|---------------------------------------------------------|---------------|------------------| +| `$uri` | Collector hostname | Yes | Non-empty string | +| `$protocol` | Collector Protocol (HTTP or HTTPS) | No | String | +| `$type` | Request Type (POST or GET) | No | String | +| `$buffer_size` | Amount of events to store before flush | No | Int | +| `$debug` | Whether or not to log errors | No | Boolean | +| `$curl_timeout` | Maximum time the request is allowed to take, in seconds | No | Int | +| `$server_anonymization` | Enable Server Anonymization for sent events | No | Int | -#### Curl Default Settings +#### Curl default settings The internal emitter default settings are as follows: @@ -140,25 +143,25 @@ The internal emitter default settings are as follows: Since version 0.8 of the PHP tracker, you can change these settings using the following setter functions: -- `$curl_emitter.setCurlAmount($curl_amount)` – update the curl buffer size (number of times we need to reach the buffer size before we initiate sending) -- `$curl_emitter.setRollingWindow($rolling_window)` – update the rolling window configuration (max number of concurrent requests) +- `$curl_emitter.setCurlAmount($curl_amount)`: update the curl buffer size (number of times we need to reach the buffer size before we initiate sending) +- `$curl_emitter.setRollingWindow($rolling_window)`: update the rolling window configuration (max number of concurrent requests) ### File :::caution -When running under Windows, PHP cannot spawn truly separate processes, and slowly eats more and more resources when more processes are spawned. Thus, Windows might crash under high load when using the File Emitter. +When running under Windows, PHP can't spawn truly separate processes, and slowly eats more and more resources when more processes are spawned. Thus, Windows might crash under high load when using the File Emitter. ::: The File Emitter is the only true non-blocking solution. The File Emitter works via spawning workers which grab created files of logged events from a local temporary folder. The workers then load the events using the same asynchronous curl properties from the above emitter. -All of the worker processes are created as background processes so none of them will delay the execution of the main script. Currently, they are configured to look for files inside created worker folders until there are none left and they hit their `timeout` limit, at which point the process will kill itself. +All of the worker processes are created as background processes so none of them delay the execution of the main script. Currently, they're configured to look for files inside created worker folders until there are none left and they hit their `timeout` limit, at which point the process terminates itself. -If the worker for any reason fails to successfully send a request it will rename the entire file to `failed` and leave it in the `/temp/failed-logs/` folder. +If the worker for any reason fails to successfully send a request it renames the entire file to `failed` and leaves it in the `/temp/failed-logs/` folder. :::note -The collector does not retry failed requests to the collector. Failed requests to the collector (e.g., due to it being not reachable) result in lost events. +The emitter doesn't retry failed requests to the Collector. Failed requests to the Collector (for example due to it being not reachable) result in lost events. ::: Example Emitter creation: @@ -167,7 +170,7 @@ Example Emitter creation: $emitter = new FileEmitter($collector_uri, false, "POST", 2, 15, 100, "/tmp/snowplow"); ``` -The buffer for the file emitter works a bit differently to the other emitters in that here it refers to the number of events needed before an `events-random.log` is produced for a worker. If you are anticipating it taking a long time to reach the buffer be aware that the worker will kill itself after 75 seconds by default (15 x 5). Adjust the timeout amount in the construction of the FileEmitter if the default is not suitable. +The buffer for the file emitter works a bit differently to the other emitters in that here it refers to the number of events needed before an `events-random.log` is produced for a worker. If you are anticipating it taking a long time to reach the buffer be aware that the worker terminates itself after 75 seconds by default (15 x 5). Adjust the timeout amount in the construction of the FileEmitter if the default isn't suitable. Constructor: @@ -188,7 +191,7 @@ Arguments: | `$debug` | Whether or not to log errors | No | Boolean | | `$log_dir` | The directory for event log and worker log subdirectories to be created in | No | String | -### Emitter Debug Mode +### Emitter debug mode Debug mode is enabled on emitters by setting the `$debug` argument in the emitter constructor to `true`: @@ -196,21 +199,21 @@ Debug mode is enabled on emitters by setting the `$debug` argument in the emitte $emitter = new SyncEmitter($collector_uri, "http", "POST", 50, true); ``` -By default, debug mode will create a new directory called `/debug/` in the root of the tracker's directory. It will then create a log file with the following structure; `sync-events-log-[[random number]].log`: i.e. the type of emitter and a randomized number to prevent it from being accidentally overwritten. +By default, debug mode creates a new directory called `/debug/` in the root of the tracker's directory. It then creates a log file with the following structure; `sync-events-log-[[random number]].log`: which is the type of emitter and a randomized number to prevent it from being accidentally overwritten. -If physically storing the information is not possible due to not having the correct write permissions or simply not wanted it can be turned off by updating the following value in the Constants class: +If physically storing the information isn't possible due to not having the correct write permissions or simply not wanted it can be turned off by updating the following value in the Constants class: ```php const DEBUG_LOG_FILES = false; ``` -Now all debugging information will be printed to the console. +Now all debugging information is printed to the console. -Every time the events buffer is flushed we will be able to see if the flush was successful. In the case of an error, it records the entire event payload the tracker was trying to send, along with the error code. +Every time the events buffer is flushed we can see if the flush was successful. In the case of an error, it records the entire event payload the tracker was trying to send, along with the error code. -#### Event Specific Information +#### Event specific information -Debug Mode if enabled will also have the emitter begin storing information internally. It will store the HTTP response code and the payload for every request made by the emitter. +If debug mode is enabled the emitter begins storing information internally. It stores the HTTP response code and the payload for every request made by the emitter. ```php array( @@ -222,7 +225,7 @@ array( The `data` is stored as a JSON-encoded string. To locally test whether or not your emitters are successfully sending, we can retrieve this information with the following commands: ```php -$emitters = $tracker->returnEmitters(); # Will store all of the emitters as an array. +$emitters = $tracker->returnEmitters(); # Store all of the emitters as an array. $emitter = $emitters[0]; # Get the first emitter stored by the tracker $results = $emitter->returnRequestResults(); # Return the stored results. @@ -233,7 +236,7 @@ print("Data: ".$results[0]["data"]); This allows you to debug on a request by request basis to ensure that everything is being sent properly. -#### Turn Debug Off +#### Turn debug off As debugging stores a lot of information, we can end debug mode by calling the following command: @@ -241,7 +244,7 @@ As debugging stores a lot of information, we can end debug mode by calling the f $tracker->turnOffDebug(); ``` -This will stop all logging activity, both to the external files and to the local arrays. We can go one step further though and pass a `true` boolean to the function. This will delete all of the tracker's associated physical debug log files as well as emptying the local arrays within each linked emitter. +This stops all logging activity, both to the external files and to the local arrays. We can go one step further though and pass a `true` boolean to the function. This deletes all of the tracker's associated physical debug log files as well as emptying the local arrays within each linked emitter. ```php $tracker->turnOffDebug(true); diff --git a/docs/sources/trackers/php-tracker/subjects/index.md b/docs/sources/trackers/php-tracker/subjects/index.md index 1887fa88c9..d3580a50b2 100644 --- a/docs/sources/trackers/php-tracker/subjects/index.md +++ b/docs/sources/trackers/php-tracker/subjects/index.md @@ -12,7 +12,7 @@ To create a new subject: $subject = new Subject(); ``` -By default the subject has one piece of information in it already, the [platform](/docs/sources/trackers/snowplow-tracker-protocol/going-deeper/event-parameters/index.md#application-parameters) `["p" => "srv"]`. +By default the subject has one piece of information in it already, the [platform](/docs/events/going-deeper/event-parameters/index.md#application-parameters) `["p" => "srv"]`. The Subject class contains a variety of 'set' methods to attach extra data to your event. @@ -66,7 +66,7 @@ For example: $subject->setPlatform("tv") # Running on a Connected TV ``` -For a full list of supported platforms, please see the [Event Parameters reference](/docs/sources/trackers/snowplow-tracker-protocol/going-deeper/event-parameters/index.md#application-parameters). +For a full list of supported platforms, please see the [Event Parameters reference](/docs/events/going-deeper/event-parameters/index.md#application-parameters). ### `setUserId` diff --git a/docs/sources/trackers/pixel-tracker/index.md b/docs/sources/trackers/pixel-tracker/index.md index 77db9b214d..11c0497796 100644 --- a/docs/sources/trackers/pixel-tracker/index.md +++ b/docs/sources/trackers/pixel-tracker/index.md @@ -76,7 +76,7 @@ You can use the Pixel tracker for click tracking aka URI redirects: - Set your collector path to `{{collector-domain}}/r/tp2?{{name-value-pairs}}` - the `/r/tp2` tells Snowplow that you are attempting a URI redirect - Add a `&u={{uri}}` argument to your collector URI, where `{{uri}}` is the URL-encoded URI that you want to redirect to - On clicking this link, the collector will register the link and then do a 302 redirect to the supplied `{{uri}}` -- As well as the `&u={{uri}}` parameter, you can populate the collector URI with any other fields from the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md) +- As well as the `&u={{uri}}` parameter, you can populate the collector URI with any other fields from the [Snowplow Tracker Protocol](/docs/events/index.md) Redirect tracking is usually disabled by default, and is disabled by default for all Snowplow BDP users. To use this feature, you need to enable this in your collector configuration. Snowplow BDP customers can enable this from within the Pipeline Configuration screen of the Snowplow BDP Console. diff --git a/docs/sources/trackers/python-tracker/previous_versions/python-v0-15/adding-extra-data-the-subject-class/index.md b/docs/sources/trackers/python-tracker/previous_versions/python-v0-15/adding-extra-data-the-subject-class/index.md index bce7051263..45265b4a24 100644 --- a/docs/sources/trackers/python-tracker/previous_versions/python-v0-15/adding-extra-data-the-subject-class/index.md +++ b/docs/sources/trackers/python-tracker/previous_versions/python-v0-15/adding-extra-data-the-subject-class/index.md @@ -46,7 +46,7 @@ For example: s.set_platform("tv") # Running on a Connected TV ``` -For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md). ### Set user ID with `set_user_id` diff --git a/docs/sources/trackers/python-tracker/previous_versions/python-v0-15/tracking-specific-events/index.md b/docs/sources/trackers/python-tracker/previous_versions/python-v0-15/tracking-specific-events/index.md index 719390a801..3868318590 100644 --- a/docs/sources/trackers/python-tracker/previous_versions/python-v0-15/tracking-specific-events/index.md +++ b/docs/sources/trackers/python-tracker/previous_versions/python-v0-15/tracking-specific-events/index.md @@ -130,7 +130,7 @@ from snowplow_tracker.tracker import TrueTimestamp tracker.track_struct_event("some cat", "save action", tstamp=TrueTimestamp(1368725287000)) ``` -Above will attach [`ttm`](/docs/sources/trackers/snowplow-tracker-protocol/index.md#timestamp-parameters)([`true_tstamp`](/docs/fundamentals/canonical-event/index.md#date--time-fields)) parameter instead of default `dtm`. You can also use, plain integer, `DeviceTimestamp` or `None` to send `device_sent_timestamp`. +Above will attach [`ttm`](/docs/events/index.md#timestamp-parameters)([`true_tstamp`](/docs/fundamentals/canonical-event/index.md#date--time-fields)) parameter instead of default `dtm`. You can also use, plain integer, `DeviceTimestamp` or `None` to send `device_sent_timestamp`. **_\*\*New to v0.9.0_** diff --git a/docs/sources/trackers/python-tracker/subject/index.md b/docs/sources/trackers/python-tracker/subject/index.md index 0f779498e2..2f816fc4cf 100644 --- a/docs/sources/trackers/python-tracker/subject/index.md +++ b/docs/sources/trackers/python-tracker/subject/index.md @@ -93,7 +93,7 @@ The default platform is `pc`. You can change the platform the subject is using b s.set_platform('mob') ``` -For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md#application-parameters). +For a full list of supported platforms, please see the [Snowplow Tracker Protocol](/docs/events/index.md#application-parameters). ### `set_user_id` diff --git a/docs/sources/trackers/python-tracker/tracking-specific-events/index.md b/docs/sources/trackers/python-tracker/tracking-specific-events/index.md index 2fc1d27590..daed8db7c9 100644 --- a/docs/sources/trackers/python-tracker/tracking-specific-events/index.md +++ b/docs/sources/trackers/python-tracker/tracking-specific-events/index.md @@ -17,7 +17,7 @@ tracker.track(page_view) Every tracked event payload has a unique event_id UUID string (`eid`). Other properties include the name_tracker (`namespace`) and `app_id` set when the Tracker was initialized. From version 1 onwards, `tracker.track()` returns the payload's `eid`. -Snowplow events have a defined structure and protocol that is identical regardless of the tracker used. Further information on this structure can be found [here](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +Snowplow events have a defined structure and protocol that is identical regardless of the tracker used. Further information on this structure can be found [here](/docs/events/index.md). The Python tracker [Github repository](https://github.com/snowplow/snowplow-python-tracker) includes 3 example apps demonstrating different ways to send events to your collector. diff --git a/docs/sources/trackers/react-native-tracker/custom-tracking-using-schemas/global-context/index.md b/docs/sources/trackers/react-native-tracker/custom-tracking-using-schemas/global-context/index.md index 951597287c..3cadec7942 100644 --- a/docs/sources/trackers/react-native-tracker/custom-tracking-using-schemas/global-context/index.md +++ b/docs/sources/trackers/react-native-tracker/custom-tracking-using-schemas/global-context/index.md @@ -67,7 +67,7 @@ This argument is a string taken from the event payload field, `e`. | Custom structured event | se | | Custom self describing event | ue | -Further information about the event payload can be found in the [tracker protocol documentation](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +Further information about the event payload can be found in the [tracker protocol documentation](/docs/events/index.md). #### `eventSchema` diff --git a/docs/sources/trackers/react-native-tracker/hybrid-apps/index.md b/docs/sources/trackers/react-native-tracker/hybrid-apps/index.md index a83b9fa6f0..5315933db4 100644 --- a/docs/sources/trackers/react-native-tracker/hybrid-apps/index.md +++ b/docs/sources/trackers/react-native-tracker/hybrid-apps/index.md @@ -34,7 +34,7 @@ We recommend using the Web tracker (v4.3+) to forward all Web events to the Reac 4. Track events as usual. -The Web tracker will automatically intercept all web events and forward them to the React Native tracker. The forwarded events will have the tracker version from Web, e.g. "js-4.1.0", but will otherwise be tracked like the mobile events. They may contain additional information not present in the React Native mobile events, such as a browser useragent string or URL, or Web context entities e.g. the [WebPage entity](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/page-views/#webpage-page-view-id-context-entity). +The Web tracker will automatically intercept all web events and forward them to the React Native tracker. The forwarded events will have the tracker version from Web, e.g. "js-4.1.0", but will otherwise be tracked like the mobile events. They may contain additional information not present in the React Native mobile events, such as a browser useragent string or URL, or Web context entities e.g. the [WebPage entity](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/page-views/index.md#webpage-page-view-id-context-entity). The forwarded events are filtered out of the Web tracker event queue so that they are not tracked twice. diff --git a/docs/sources/trackers/react-native-tracker/migration-guides/migrating-from-v2-x-to-v4/index.md b/docs/sources/trackers/react-native-tracker/migration-guides/migrating-from-v2-x-to-v4/index.md index da72d248c1..1fddefb594 100644 --- a/docs/sources/trackers/react-native-tracker/migration-guides/migrating-from-v2-x-to-v4/index.md +++ b/docs/sources/trackers/react-native-tracker/migration-guides/migrating-from-v2-x-to-v4/index.md @@ -42,7 +42,7 @@ Read more [in the documentation here](/docs/sources/trackers/react-native-tracke ### Removed geolocation context entity The geolocation context entity is no longer available to be tracked by the tracker. -You may track it manually using global context and [the geolocation schema](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/geolocation/index.md#geolocation-context-entity-tracked-in-apps). +You may track it manually using global context and [the geolocation schema](/docs/events/ootb-data/geolocation/index.md#geolocation-context-entity-tracked-in-apps). ### Removed exception and diagnostic autotracking diff --git a/docs/sources/trackers/react-native-tracker/previous-version/react-native-tracker-v2-reference/tracking-events/lifecycle-tracking/index.md b/docs/sources/trackers/react-native-tracker/previous-version/react-native-tracker-v2-reference/tracking-events/lifecycle-tracking/index.md index 8e3f3a3860..58030894d3 100644 --- a/docs/sources/trackers/react-native-tracker/previous-version/react-native-tracker-v2-reference/tracking-events/lifecycle-tracking/index.md +++ b/docs/sources/trackers/react-native-tracker/previous-version/react-native-tracker-v2-reference/tracking-events/lifecycle-tracking/index.md @@ -28,8 +28,8 @@ const tracker = createTracker( ); ``` -Once enabled, the tracker will automatically track a [`Background` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#background-event) when the app is moved to background and a [`Foreground` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#foreground-event) when the app moves back to foreground (becomes visible in the screen). +Once enabled, the tracker will automatically track a [`Background` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#background-event) when the app is moved to background and a [`Foreground` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#foreground-event) when the app moves back to foreground (becomes visible in the screen). -The tracker attaches a [`LifecycleEntity`](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#lifecycle-context-entity) to all the events tracked by the tracker reporting if the app was visible (foreground state) when the event was tracked. +The tracker attaches a [`LifecycleEntity`](/docs/events/ootb-data/mobile-lifecycle-events/index.md#lifecycle-context-entity) to all the events tracked by the tracker reporting if the app was visible (foreground state) when the event was tracked. The `LifecycleEntity` value is conditioned by the internal state of the tracker only. To make an example, if the app is in foreground state but the developer tracks a `Background` event intentionally, it would force the generation of a `LifecycleEntity` that mark the app as non visible, even if it's actually visible in the device. diff --git a/docs/sources/trackers/react-native-tracker/previous-version/react-native-tracker-v2-reference/tracking-events/screen-tracking/index.md b/docs/sources/trackers/react-native-tracker/previous-version/react-native-tracker-v2-reference/tracking-events/screen-tracking/index.md index 70c159dcc8..100c711300 100644 --- a/docs/sources/trackers/react-native-tracker/previous-version/react-native-tracker-v2-reference/tracking-events/screen-tracking/index.md +++ b/docs/sources/trackers/react-native-tracker/previous-version/react-native-tracker-v2-reference/tracking-events/screen-tracking/index.md @@ -68,11 +68,11 @@ Concretely, it consists of the following metrics: 3. Number of list items scrolled out of all list items (requires some manual tracking). 4. Scroll depth in pixels (requires some manual tracking). -This information is attached using a [`screen_summary` context entity](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md#screen-summary-entity) to the following events: +This information is attached using a [`screen_summary` context entity](/docs/events/ootb-data/page-activity-tracking/index.md#screen-summary-entity) to the following events: -1. [`screen_end` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md#screen-end-event) that is automatically tracked before a new screen view event. -2. [`application_background` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#background-event). -3. [`application_foreground` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#foreground-event). +1. [`screen_end` event](/docs/events/ootb-data/page-activity-tracking/index.md#screen-end-event) that is automatically tracked before a new screen view event. +2. [`application_background` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#background-event). +3. [`application_foreground` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#foreground-event). Screen engagement tracking is enabled by default, but can be configured using the `TrackerConfiguration.screenEngagementAutotracking` option. diff --git a/docs/sources/trackers/react-native-tracker/tracking-events/lifecycle-tracking/index.md b/docs/sources/trackers/react-native-tracker/tracking-events/lifecycle-tracking/index.md index f3b095d2f2..8030af6aed 100644 --- a/docs/sources/trackers/react-native-tracker/tracking-events/lifecycle-tracking/index.md +++ b/docs/sources/trackers/react-native-tracker/tracking-events/lifecycle-tracking/index.md @@ -22,8 +22,8 @@ const tracker = await newTracker({ }); ``` -Once enabled, the tracker will automatically track a [`Background` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#background-event) when the app is moved to background and a [`Foreground` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#foreground-event) when the app moves back to foreground (becomes visible in the screen). +Once enabled, the tracker will automatically track a [`Background` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#background-event) when the app is moved to background and a [`Foreground` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#foreground-event) when the app moves back to foreground (becomes visible in the screen). -The tracker attaches a [`LifecycleEntity`](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#lifecycle-context-entity) to all the events tracked by the tracker reporting if the app was visible (foreground state) when the event was tracked. +The tracker attaches a [`LifecycleEntity`](/docs/events/ootb-data/mobile-lifecycle-events/index.md#lifecycle-context-entity) to all the events tracked by the tracker reporting if the app was visible (foreground state) when the event was tracked. The `LifecycleEntity` value is conditioned by the internal state of the tracker only. To make an example, if the app is in foreground state but the developer tracks a `Background` event intentionally, it would force the generation of a `LifecycleEntity` that mark the app as non visible, even if it's actually visible in the device. diff --git a/docs/sources/trackers/react-native-tracker/tracking-events/platform-and-application-context/index.md b/docs/sources/trackers/react-native-tracker/tracking-events/platform-and-application-context/index.md index 1ccabcb898..816524f1a7 100644 --- a/docs/sources/trackers/react-native-tracker/tracking-events/platform-and-application-context/index.md +++ b/docs/sources/trackers/react-native-tracker/tracking-events/platform-and-application-context/index.md @@ -45,12 +45,12 @@ Additionally, you can track the build name of the application (e.g., `s9f2k2d` o Depending on whether `build` property is configured, the information will be tracked in a context entity using either of these schemas: -1. If only `appVersion` is configured, [the Web `application` entity is used](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/app-information/index.md#application-context-entity-on-web-apps). -2. If both `appVersion` and `build` are configured, [the mobile `application` entity is used](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/app-information/index.md#application-context-entity-on-mobile-apps). +1. If only `appVersion` is configured, [the Web `application` entity is used](/docs/events/ootb-data/app-information/index.md#application-context-entity-on-web-apps). +2. If both `appVersion` and `build` are configured, [the mobile `application` entity is used](/docs/events/ootb-data/app-information/index.md#application-context-entity-on-mobile-apps). ## Platform context -The [platform context entity](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/device-and-browser/index.md#mobile-context) contains information about the user's device. +The [platform context entity](/docs/events/ootb-data/device-and-browser/index.md#mobile-context) contains information about the user's device. By default only the following properties are tracked automatically: diff --git a/docs/sources/trackers/react-native-tracker/tracking-events/screen-tracking/index.md b/docs/sources/trackers/react-native-tracker/tracking-events/screen-tracking/index.md index fd1397492d..0f8036472d 100644 --- a/docs/sources/trackers/react-native-tracker/tracking-events/screen-tracking/index.md +++ b/docs/sources/trackers/react-native-tracker/tracking-events/screen-tracking/index.md @@ -67,11 +67,11 @@ Concretely, it consists of the following metrics: 3. Number of list items scrolled out of all list items (requires some manual tracking). 4. Scroll depth in pixels (requires some manual tracking). -This information is attached using a [`screen_summary` context entity](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md#screen-summary-entity) to the following events: +This information is attached using a [`screen_summary` context entity](/docs/events/ootb-data/page-activity-tracking/index.md#screen-summary-entity) to the following events: -1. [`screen_end` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md#screen-end-event) that is automatically tracked before a new screen view event. -2. [`application_background` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#background-event). -3. [`application_foreground` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#foreground-event). +1. [`screen_end` event](/docs/events/ootb-data/page-activity-tracking/index.md#screen-end-event) that is automatically tracked before a new screen view event. +2. [`application_background` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#background-event). +3. [`application_foreground` event](/docs/events/ootb-data/mobile-lifecycle-events/index.md#foreground-event). Screen engagement tracking is enabled by default, but can be configured using the `TrackerConfiguration.screenEngagementAutotracking` option. diff --git a/docs/sources/trackers/roku-tracker/adding-data/index.md b/docs/sources/trackers/roku-tracker/adding-data/index.md index bd16611ddf..2e75cb07e7 100644 --- a/docs/sources/trackers/roku-tracker/adding-data/index.md +++ b/docs/sources/trackers/roku-tracker/adding-data/index.md @@ -57,7 +57,7 @@ This information can be entered during tracker initialization by passing a `sub Some subject information is filled automatically by the tracker. This includes the platform of the user, timezone, language, resolution, and viewport. -The following table lists all the properties that can be set in tracker initialization. These are all part of the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +The following table lists all the properties that can be set in tracker initialization. These are all part of the [Snowplow Tracker Protocol](/docs/events/index.md). | Property | Description | | --------------- | --------------------------------------- | diff --git a/docs/sources/trackers/roku-tracker/tracking-events/index.md b/docs/sources/trackers/roku-tracker/tracking-events/index.md index 38619153cf..4949bb692a 100644 --- a/docs/sources/trackers/roku-tracker/tracking-events/index.md +++ b/docs/sources/trackers/roku-tracker/tracking-events/index.md @@ -18,7 +18,7 @@ Tracking methods supported by the Roku Tracker: All the methods share common features and parameters. Every type of event can have an optional context added. A Timestamp can also be provided for all event types to override the default event timestamp. See the next page to learn about adding extra data to events. It's important to understand how event context works, as it is one of the most powerful Snowplow features. Adding event context is a way to add depth, richness and value to all of your events. -Snowplow events are all processed into the same format, regardless of the event type (and regardless of the tracker language used). Read about the different properties and fields of events in the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +Snowplow events are all processed into the same format, regardless of the event type (and regardless of the tracker language used). Read about the different properties and fields of events in the [Snowplow Tracker Protocol](/docs/events/index.md). We will first discuss the custom event tracking methods, followed by the out-of-the-box event types. Note that you can also design and create your own page view, or screen view, using `selfDescribing`, to fit your business needs better. The out-of-the-box event types are provided so you can get started with generating event data quickly. diff --git a/docs/sources/trackers/ruby-tracker/adding-data-events/index.md b/docs/sources/trackers/ruby-tracker/adding-data-events/index.md index 5f8b6d235f..2803fd2ea1 100644 --- a/docs/sources/trackers/ruby-tracker/adding-data-events/index.md +++ b/docs/sources/trackers/ruby-tracker/adding-data-events/index.md @@ -91,7 +91,7 @@ Your server-side code may not have access to all these parameters, or they might You could create and define a new Subject for every user or every event you want to track. Attaching that Subject to the `track_x_event` method call would add those properties to your event. Alternatively, you could swap the tracker-associated Subject for a more appropriate one before tracking the event, using `set_subject`. -The following table lists all the properties that can be set via Subject. These are all part of the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). Check out the [API docs](https://snowplow.github.io/snowplow-ruby-tracker/SnowplowTracker/Subject.html) for the details of how to set these parameters. +The following table lists all the properties that can be set via Subject. These are all part of the [Snowplow Tracker Protocol](/docs/events/index.md). Check out the [API docs](https://snowplow.github.io/snowplow-ruby-tracker/SnowplowTracker/Subject.html) for the details of how to set these parameters. | Property | **Description** | | ------------------------------------------ | ----------------------------------------------------------------- | diff --git a/docs/sources/trackers/ruby-tracker/tracking-events/index.md b/docs/sources/trackers/ruby-tracker/tracking-events/index.md index cbcd380536..3cdc15e88a 100644 --- a/docs/sources/trackers/ruby-tracker/tracking-events/index.md +++ b/docs/sources/trackers/ruby-tracker/tracking-events/index.md @@ -25,7 +25,7 @@ Tracking methods supported by the Ruby Tracker: All the `track_x_event` methods share common features and parameters. Every type of event can have an optional context, Subject, and Page added. A Timestamp can also be provided for all event types to override the default event timestamp. See [the next page](/docs/sources/trackers/ruby-tracker/adding-data-events/index.md) to learn about adding extra data to events. It's important to understand how event context works, as it is one of the most powerful Snowplow features. Adding event context is a way to add depth, richness and value to all of your events. -Snowplow events are all processed into the same format, regardless of the event type (and regardless of the tracker language used). Read about the different properties and fields of events in the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +Snowplow events are all processed into the same format, regardless of the event type (and regardless of the tracker language used). Read about the different properties and fields of events in the [Snowplow Tracker Protocol](/docs/events/index.md). We will first discuss the custom event tracking methods, followed by the out-of-the-box event types. Note that you can also design and create your own page view, screen view, or eCommerce events, using `track_self_describing_event`, to fit your business needs better. The out-of-the-box event types are provided so you can get started with generating event data quickly. diff --git a/docs/sources/trackers/rust-tracker/initialization-and-configuration/index.md b/docs/sources/trackers/rust-tracker/initialization-and-configuration/index.md index 4cad3d2906..f60faa27e8 100644 --- a/docs/sources/trackers/rust-tracker/initialization-and-configuration/index.md +++ b/docs/sources/trackers/rust-tracker/initialization-and-configuration/index.md @@ -27,7 +27,7 @@ The required attributes of the `Snowplow::create_tracker` method are `namespace` Subject information are persistent and global information about the tracked device or user. They apply to all events and are assigned as event properties. -The configured attributes are mapped to Snowplow event properties described in the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). They are mapped as follows: +The configured attributes are mapped to Snowplow event properties described in the [Snowplow Tracker Protocol](/docs/events/index.md). They are mapped as follows: | Attribute | Event Property | | ----------------- | ---------------- | diff --git a/docs/sources/trackers/rust-tracker/tracking-events/index.md b/docs/sources/trackers/rust-tracker/tracking-events/index.md index 73addb6490..7bc8d1f5fc 100644 --- a/docs/sources/trackers/rust-tracker/tracking-events/index.md +++ b/docs/sources/trackers/rust-tracker/tracking-events/index.md @@ -22,7 +22,7 @@ Event classes supported by the Rust Tracker: All the methods share common features and parameters. Every type of event can have an optional context added. See the [next page](/docs/sources/trackers/rust-tracker/adding-data/index.md) to learn about adding extra data to events. It's important to understand how event context works, as it is one of the most powerful Snowplow features. Adding event context is a way to add depth, richness and value to all of your events. -Snowplow events are all processed into the same format, regardless of the event type (and regardless of the tracker language used). Read about the different properties and fields of events in the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md). +Snowplow events are all processed into the same format, regardless of the event type (and regardless of the tracker language used). Read about the different properties and fields of events in the [Snowplow Tracker Protocol](/docs/events/index.md). We will first discuss the custom event types, followed by the out-of-the-box event types. Note that you can also design and create your own page view, or screen view, using `SelfDescribingEvent`, to fit your business needs better. The out-of-the-box event types are provided so you can get started with generating event data quickly. diff --git a/docs/sources/trackers/snowplow-tracker-protocol/index.md b/docs/sources/trackers/snowplow-tracker-protocol/index.md deleted file mode 100644 index 2d5348b99e..0000000000 --- a/docs/sources/trackers/snowplow-tracker-protocol/index.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "Snowplow events" -description: "" -date: "2020-02-26" -sidebar_position: 80 ---- - -# Snowplow event specification - -At its heart, Snowplow is a platform for granular tracking of events. -Snowplow trackers fire _events_, which are either HTTP GET or POST requests to a Snowplow collector. By adding parameters to these requests, trackers can pass data into the collector for processing by Snowplow. - -This section aims to give an overview of Snowplow events. -It lists the available data types and links to the tracking and modeling documentation for them. -If you are interested in an overview of the properties in the atomic events table, [please refer to this page](/docs/fundamentals/canonical-event/index.md). - -## Custom events and context entities - -Snowplow data is designed to be able to tailor to your business needs using custom events and context entities. - -Category | Description ----|--- -[Context entities](/docs/sources/trackers/snowplow-tracker-protocol/custom-events/context-entities/index.md) | Add information to events using reusable entities. -[Self-describing events](/docs/sources/trackers/snowplow-tracker-protocol/custom-events/self-describing-events/index.md) | Track custom events with schemas. -[Structured events](/docs/sources/trackers/snowplow-tracker-protocol/custom-events/structured-events/index.md) | Track custom events without schemas (not recommended – we recommend tracking self-describing events instead). - -## Out-of-the-box data - -Snowplow also provides out-of-the-box events, context entities and atomic event properties for common Web and mobile use cases. - -Category | Description ----|--- -[Page and screen view events](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-and-screen-view-events/index.md) | Basic building block for tracking views of Web pages or mobile screens. -[Page activity events](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md) | Tracking user engagement on the Web page using page pings. -[Mobile app lifecycle events](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md) | Events to track mobile app lifecycle (install, going to foreground, background). -[Referrers, deep links and cross-navigation events](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/links-and-referrers/index.md) | Events and properties to track referrer information and linking between apps and websites. -[App error events](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/app-error-events/index.md) | Tracking errors and exceptions from apps. -[Consent events](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/consent-events/index.md) | Events for tracking user consent. -[E-commerce events](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/ecommerce-events/index.md) | Events for tracking e-commerce transactions and more. -[Media events](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/media-events/index.md) | Tracking media playback in Web or mobile apps. -[Performance metrics](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/app-performance/index.md) | Events to track performance metrics from websites and apps. -[App information](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/app-information/index.md) | Information about the app that the events originate from. -[Device and browser information](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/device-and-browser/index.md) | Information about the device or browser of the user. -[User and session identification and stitching](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/user-and-session-identification/index.md) | Overview of the user and session identifiers provided by the trackers and how to stitch them. -[Geolocation information](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/geolocation/index.md) | Geolocation information attached to events. - -
- Going deeper into the event properties -
- -These pages are for you if you want to understand the tracker payload in more detail, and especially if you are building your own tracker. In the latter case, utilizing the parameters documented here will ensure that your tracker works with the rest of the Snowplow stack. - -Category | Description ----|--- -[Event parameters](/docs/sources/trackers/snowplow-tracker-protocol/going-deeper/event-parameters/index.md) | Protocol of all the parameters in the event payload. -[HTTP headers](/docs/sources/trackers/snowplow-tracker-protocol/going-deeper/http-headers/index.md) | Collecting HTTP request headers and cookies. -[Example requests](/docs/sources/trackers/snowplow-tracker-protocol/going-deeper/example-requests/index.md) | Example tracker requests with sample payload. - -
-
diff --git a/docs/sources/trackers/webview-tracker/index.md b/docs/sources/trackers/webview-tracker/index.md index 7e80a535a6..63cd1081ab 100644 --- a/docs/sources/trackers/webview-tracker/index.md +++ b/docs/sources/trackers/webview-tracker/index.md @@ -13,14 +13,14 @@ import {versions} from '@site/src/componentVersions'; ``` -

The Snowplow WebView Tracker allows you to track Snowplow events from Web views in mobile hybrid apps. The current tracker version is {versions.webViewTracker}.

+

The Snowplow WebView Tracker allows you to track Snowplow events from web views in mobile hybrid apps. The current tracker version is {versions.webViewTracker}.

-Hybrid apps are mobile apps that in addition to a native interface, provide part of the UI through an embedded Web view. -Snowplow events are tracked from both the native code (e.g. written in Swift or Kotlin) as well as the Web view (in JavaScript). -Our goal is to have both events tracked from the native code as well as the Web view, share the same session and appear as tracked with the same tracker. +Hybrid apps are mobile apps that in addition to a native interface, provide part of the UI through an embedded web view. +Snowplow events are tracked from both the native code (e.g. written in Swift or Kotlin) as well as the web view (in JavaScript). +The goal is to have events that are tracked from the native code and web view share the same session, and appear as tracked with the same tracker. :::tip -We recommend using the [Snowplow Web tracker](/docs/sources/trackers/javascript-trackers/index.md) with [WebView plugin](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/webview/index.md) (which uses the WebView tracker as a dependency), rather than using this tracker directly. +We recommend using the [Snowplow web tracker](/docs/sources/trackers/javascript-trackers/index.md) with [WebView plugin](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/webview/index.md) (which uses the WebView tracker as a dependency), rather than using this tracker directly. The WebView plugin automatically forwards all tracked events to the mobile tracker. Events must be manually tracked when using the WebView tracker by itself. ::: @@ -83,7 +83,7 @@ import { trackSelfDescribingEvent } from '@snowplow/webview-tracker'; -You may download the `sp.js` file from the [Releases section on Github](https://github.com/snowplow-incubator/snowplow-webview-tracker/releases), self-host it, and load to your page using the following tag: +You may download the `sp.js` file from the [Releases section on GitHub](https://github.com/snowplow-incubator/snowplow-webview-tracker/releases), self-host it, and load to your page using the following tag: ```html