The Data Layer is a powerful feature, providing you with fine-grained control over the data sent to various analytics. This guide will walk you through the essentials of crafting a Data Layer to enhance your data collection strategy.

​
Introduction to Edgee Data Layer

A Data Layer is a structured data format used to define and send detailed information about user interactions, page characteristics, and more, directly within your HTML page. By including a Data Layer, you can instruct Edgee on exactly what data to collect, how to process it, and where to send it.

​
Inserting a Data Layer in your application

The way you insert a Data Layer in your application depends on the Edgee SDK you’re using. For HTML applications you can manually insert the Data Layer within a <script> tag with type="application/json" and a specific ID.

For React applications, you can use the EdgeeDataLayer component from the react-edgee package.

<script id="__EDGEE_DATA_LAYER__" type="application/json">
{
    ...YOUR_DATA_LAYER...
}
</script>
You can place your Data Layer anywhere in your page, but it’s recommended to include it before the Edgee SDK for optimal performance.

​
Structure of a Data Layer object

Please note that the typical Data Layer object is very small and only includes one or two events. You can find a few examples of valid objects at the end of this page.

The following code represents the full schema of everything you can define in your Data Layer:

{
  "data_collection": {
    "events": [
      {
        "type": "page",
        "data": {
            "name": "With Edgee",
            "category": "demo",
            "title": "With Edgee",
            "url": "https://demo.edgee.app/with-edgee.html",
            "path": "/with-edgee.html",
            "search": "?ok",
            "referrer": "https://demo.edgee.app/previous-page",
            "keywords": [
              "demo",
              "tag manager",
              "edgee"
            ],
            "properties": {
              "section": "political",
              "pv": 1
            }
        },
        "components": {
            "all": false,
            "edgee/google-analytics": true
        }
      },
      {
        "type": "track",
        "data": {
            "name": "button click",
            "properties": {
              "color": "blue",
              "category": "test",
              "label": "button click"
            }
        },
        "components": {
            "all": false,
            "edgee/google-analytics": true
        }
      },
      {
        "type": "user",
        "data": {
            "user_id": "12345",
            "anonymous_id": "12345",
            "properties": {
              "email": "me@example.com",
              "name": "John Doe"
            }
        }
      }
    ],
    "context": {
        "page": {
            "name": "With Edgee",
            "category": "demo",
            "title": "With Edgee",
            "url": "https://demo.edgee.app/with-edgee.html",
            "path": "/with-edgee.html",
            "search": "?ok",
            "referrer": "https://demo.edgee.app/previous-page",
            "keywords": [
              "demo",
              "tag manager",
              "edgee"
            ],
            "properties": {
              "section": "political",
              "pv": 1
            }
        },
        "user": {
            "user_id": "12345",
            "anonymous_id": "12345",
            "properties": {
              "email": "me@example.com",
              "name": "John Doe"
            }
        }
    },
    "components": {
        "all": false,
        "edgee/google-analytics": true
    }
  }
}

​
Data Layer fields breakdown

The following fields are defined under data_collection:

FieldTypeDescription
eventsoptionalArrayContains a list of events (see below for the event structure).
contextoptionalObjectContains general information that can be used for all events.
componentsoptionalObjectSpecifies which components should receive the data. This enables targeted data transmission based on your configuration.

Let’s have a look at each field individually.

​
The events list

It contains objects with the following structure.

FieldTypeDescription
typerequiredStringThe type of event: page, track, or user.
dataoptionalObjectThe data structure depends on the event type (see detailed pages). This is required for track events.
componentsoptionalObjectSpecifies which components should receive the data.

Learn more about the page, track, and user event types and their structure.

​
The context object

It can contain the following fields.

FieldTypeDescription
pageoptionalObjectGeneral info about this page that can be used across events.
useroptionalObjectGeneral info about the user that can be used across events.

Note: when you define context data about the current page or user, it’s going to be used automatically for all compatible events, so you don’t need to provide the same information multiple times. For example, data_collection.context.user is used to define the data fields for user events.

​
The components object

It can contain the following fields.

FieldTypeDescription
alloptionalBooleanEven if you don’t define this field, it will be set to true by default. But if you set it to false, no component will receive the data.
<component_name>optionalBooleanIf true, the specified component will receive the data. If false, the component will not receive the data.

Use the components object to specify which analytics components should and should not receive the data. If you do not specify any component, all configured components will receive the data by default.

You can find a few examples in the next section.

Remember: the components object can be set globally for all data collection or for individual events. This gives you full control and the ability to be very granular about what data is sent to which components. Please also note that the components object defined for an individual event will override the global configuration for that event.

​
Examples of valid Data Layer objects

​
Minimal Data Layer

{
    "data_collection": {
        "events": [
            {
                "type": "page"
            }
        ]
    }
}

​
Data Layer with context

{
    "data_collection": {
        "events": [
            {
                "type": "page"
            }
        ],
        "context": {
            "page": {
                "name": "With Edgee",
                "category": "demo",
                "title": "With Edgee",
                "url": "https://demo.edgee.app/with-edgee.html",
                "path": "/with-edgee.html",
                "search": "?ok"
            }
        }
    }
}

​
Data Layer with components control

{
    "data_collection": {
        "events": [
            ...
        ],
        "components": {
            "all": false
        }
    }
}

​
Best Practices

  • Precision and Clarity: Ensure that each field in the data layer is accurately defined. Clear, descriptive values for page names, categories, and properties enhance data quality.
  • Consent and Privacy: When including any personally identifiable information (PII) in the identify section, ensure you have obtained explicit consent from the user in compliance with GDPR, CCPA, and other privacy regulations.
  • Regular Updates: Keep your Data Layer up to date with any changes in your site structure, user attributes, or analytics components to maintain data accuracy and relevance.