Installation

Installer App

As outlined in the quickstart, Decode GA4 is accessed via a Google Cloud Marketplace subscription. It is usage-based, so there is no charge or commitment upon subscription.

Manual Installation

If you install Decode GA4 on a project/region level, you then have direct access to the deployment, installation and execution functions and can install Decode GA4 onto individual properties in code. This gives fine-grained control over deployment location and options, and provides tools to customize installation and troubleshoot any potential issues experienced.

Installation involves setting the configuration options and then executing the deploy_installer function in the region in which your GA4 dataset is located.

Common patterns are described below. Note that these assume installation in the europe-west2 region, however this dataset name will be different depending on your deployment region.

Example Usage

Quick Install (External)

This is the most common installation pattern as it pushes transformed event data to Google Cloud Storage and creates an external table in BigQuery for subsequent usage. It also unlocks cross-cloud and external compute options by supporting direct connection to transformed data in GCS.

This pattern supports automatic schema and parameter evolution by default, so will only process each date partition precisely once, and will never require a full table rebuild.

DECLARE options JSON;

SET options = JSON '''
    {
        "ga4_dataset_id": "project_id.ga4_dataset_name",
        "transform_config_template": "events_external",
        "gcs_bucket_name": "bucketname"
    }
    ''';

EXECUTE IMMEDIATE (
    SELECT `project_id.decode_ga4_europe_west2.deploy_installer`(options)
    );

CALL `project_id.ga4_dataset_name.install_decode_ga4`();

CALL `project_id.decode_ga4_dataset_name.RUN`(NULL);

Quick Install (Partitioned)

This is a simpler pattern which creates a date-partitioned table containing transformed event data. It does not require a GCS bucket, so data can only be accessed by querying the BigQuery table directly.

Incorporating any schema or parameter changes into the table will require a full table rebuild each time the new changes are to be incorporated.

DECLARE options JSON;

SET options = JSON '''
    {
        "ga4_dataset_id": "project_id.ga4_dataset_name",
        "transform_config_template": "events_partitioned"
    }
    ''';

EXECUTE IMMEDIATE (
    SELECT `project_id.decode_ga4_europe_west2.deploy_installer`(options)
    );

CALL `project_id.ga4_dataset_name.install_decode_ga4`();

CALL `project_id.decode_ga4_dataset_name.RUN`(NULL);

Install to Custom Dataset (External)

Setting the deployment_dataset_id in the options will deploy Decode GA4 resources and the output events table into the defined dataset instead of the decode_analytics_xxxxxxxx dataset.

DECLARE options JSON;

SET options = JSON '''
    {
        "ga4_dataset_id": "project_id.ga4_dataset_name",
        "transform_config_template": "events_external",
        "gcs_bucket_name": "bucketname",
        "deployment_dataset_id": "project_id.custom_dataset_name"
    }
    ''';


EXECUTE IMMEDIATE (
    SELECT `project_id.decode_ga4_europe_west2.deploy_installer`(options)
    );

CALL `project_id.ga4_dataset_name.install_decode_ga4`();

CALL `deployment_dataset_id.RUN`(NULL);

Setting the deployment_dataset_id here will override the destination for all resources and the output events table.

Install with Alternative Destination Dataset (External)

This pattern is used when you want to create the output tables in a different dataset to the source GA4 data and the deployed Decode GA4 resources. This may be desirable if using the transformed events table as an input to subsequent transformations in e.g. Dataform or DBT.

This will deploy the transformed events table to the dataset defined by the destination_dataset_id, and the Decode GA4 resources to the decode_analytics_xxxxxxxx dataset.

DECLARE options JSON;

SET options = JSON '''
    {
        "ga4_dataset_id": "project_id.ga4_dataset_name",
        "transform_config_template": "events_external",
        "gcs_bucket_name": "bucketname",
        "destination_dataset_id": "project_id.destination_dataset_name"
    }
    ''';


EXECUTE IMMEDIATE (
    SELECT `project_id.decode_ga4_europe_west2.deploy_installer`(options)
    );

CALL `project_id.ga4_dataset_name.install_decode_ga4`();

CALL `destination_dataset_id.RUN`(NULL);

To deploy Decode GA4 resources to a different, specifically-defined dataset, use the deployment_dataset_id option in combination with the destination_dataset_id option.

App Stream Install (External)

This will install Decode GA4 for an App stream, which includes app-specific event names and parameters by default.

DECLARE options JSON;

SET options = JSON '''
    {
        "ga4_dataset_id": "project_id.ga4_dataset_name",
        "transform_config_template": "events_external",
        "gcs_bucket_name": "bucketname",
        "stream_type": "app"
    }
    ''';

EXECUTE IMMEDIATE (
    SELECT `project_id.decode_ga4_europe_west2.deploy_installer`(options)
    );

CALL `project_id.ga4_dataset_name.install_decode_ga4`();

CALL `project_id.decode_ga4_dataset_name.RUN`(NULL);

Argument Reference

• ga4_dataset_id - (Required) The project_id.dataset_name of the dataset containing your GA4 BigQuery export.

• transform_config_template - (Required) The name of the transformation configuration template to use, events_external or events_partitioned.

• gcs_bucket_name - (Required for events_external config) The name of the Google Cloud Storage bucket in which to store compressed, transformed data.

• deployment_dataset_id - (Optional) The project_id.dataset_name of the dataset into which Decode GA4 will be deployed. Default is project_id.decode_analytics_xxxxxxxx, aligned to your ga4_dataset_id integer suffix.

• destination_dataset_id - (Optional) The project_id.dataset_name of the dataset into which the output eventstable will be built and maintained.

• stream_type - (Optional) The type of GA4 stream (app/web/all), which defines default values for event names and parameters. Default is web.

Event Names

• include_observed_events - (Optional) Boolean to determine whether to include observed events in the transform. Default is true.

• include_default_events - (Optional) Boolean to determine whether to include default events for the stream_type in the the transform. Default is true.

• conversion_event_names - (Optional) Array of event_name values to classify as conversions. Default is ['purchase'].

• exclude_event_names - (Optional) Array of event_name values to exclude from the transform.

• custom_event_names - (Optional) Array of additional event_name values to be included in the transform.

Event Parameters

• include_observed_event_params - (Optional) Boolean to determine whether to include observed event parameters in the transform. Default is true.

• include_default_event_params - (Optional) Boolean to determine whether to include default event parameters for the stream_type in the transform. Default is true.

• exclude_event_params - (Optional) Array of event_param names to exclude from the transform.

• custom_event_params - (Optional) JSON array of event_param name and type (string, int, float) to be included in the transform (e.g. JSON'[{"name": "new_parameter", "type": "string"}]').

User Properties

• include_observed_user_properties - (Optional) Boolean to determine whether to include observed user properties in the transform. Default is true.

• exclude_user_properties - (Optional) Array of user_property names to exclude from the transform.

• custom_user_properties - (Optional) JSON array of user_property name and type (string, int, float) values to be included in the transform (e.g. JSON'[{"name": "new_property", "type": "string"}]').

Item Parameters

• include_observed_item_params - (Optional) Boolean to determine whether to include observed item parameters in the transform. Default is true.

• exclude_item_params - (Optional) Array of item_param names to exclude from the transform.

• custom_item_params - (Optional) JSON array of item_param name and type (string, int, float) values to be included in the transform (e.g. JSON'[{"name": "new_parameter", "type": "string"}]').