Custom Dimensions

Gamera supports the concept of custom dimensions. A custom dimension is meta data that you would like to associate with a particular visit. For example, you might have some first party data about the food preferences of a current visitor that you would like to track in Gamera analytics (Visitor likes pizza).

Standard Dimensions

Before you add a custom dimension it is important to know that Gamera tracks the following standard dimensions automatically for visitors. You do not need to pass a custom dimension for any of the following types of dimensions:

What are UTM Parameters?

UTM parameters (Urchin Tracking Module parameters) are tags that you add to a URL in order to track the effectiveness of online marketing campaigns across traffic sources and publishing media. They are used in web analytics to measure and analyze the performance of campaigns by providing detailed information about the traffic coming to your website.

Common UTM Parameters:

1. utm_source: Identifies the source of the traffic, such as a search engine (e.g., Google), a social network (e.g., Facebook), a newsletter, or a website.

2. utm_medium: Identifies the medium or channel used to bring the traffic, such as email, cost-per-click (CPC), social media, or affiliate.

3. utm_campaign: Identifies a specific campaign or promotion, allowing you to track the performance of a specific marketing effort (e.g., summer_sale, launch_campaign).

4. utm_term: Identifies the paid search keywords. This parameter is used to track the specific keywords for paid search campaigns.

5. utm_content: Differentiates similar content or links within the same ad, email, or campaign, helping to track which version of a link or content was more effective.

Example of a URL with UTM Parameters:

https://www.example.com/?utm_source=google&utm_medium=cpc&utm_campaign=spring_sale&utm_term=running_shoes&utm_content=ad1

In this example:

•	utm_source=google indicates the traffic came from Google.
•	utm_medium=cpc indicates the medium is cost-per-click.
•	utm_campaign=spring_sale specifies the campaign name.
•	utm_term=running_shoes specifies the search keyword.
•	utm_content=ad1 differentiates this link from other links within the same campaign.

Using UTM parameters allows marketers to track the performance of various marketing efforts, understand user behavior, and optimize future campaigns based on data-driven insights.

Tracking Custom Dimensions

If you would like to attach additional dimensions to your visitors not tracked by our standard dimensions you must complete the following two steps:

1. Add the custom dimension to the list of allowed dimensions in the Gamera Site Manager

2. Pass the custom dimension from your site by adding some additional Javascript to your page.

Adding Custom Dimension to Allowed Dimensions

Gamera will reject all dimensions that are not added by you or your team members to the list of allowed dimensions in the Gamera Site Manager. Please note, each site has its own inclusion list. You can add an approved custom dimension by following these simple steps

1. In the Gamera Portal click on Site Manager tab

2. From the Site Manager tab, click on the Actions Menu of the site you wish to add the dimension to

3. Select Edit Custom Dimensions from the site Actions Menu

   

4. From the Custom Dimensions page, select New Dimension

   

5. Enter the name of your custom dimensions

6. Click Ok to add the custom dimension

   

Passing in Custom Dimensions from your Site

In order to consume your new custom dimension, you must pass the dimension along with its value from your site to Gamera using our on page library.

window.gamera = window.gamera || {};
window.gamera.cmd = window.gamera.cmd || [];
window.gamera.cmd.push(function() {
    window.gamera.addDimensions({
        // List your custom dimensions as 
        // key value pairs here
        "favorite_food": "pizza",
        // If your dimension contains 
        // multiple values, separate 
        // them with commas
        "multi-value-dimension": "value1,value2,value3",
        // If your dimension contains
        // a single value, pass it as 
        // a string
        "single-value-dimension": "this-is-a-test-value"
    });
});

Custom Dimension Limitations

The following limits are applied to custom dimensions:

• You can have at most 50 custom dimensions (keys)

• There is a 100 character limit per key-value pair (the name and value of the custom dimension combined).

• Multi dimension values are treated as multiple custom dimensions. For example animal=bird,dog are treated as two custom dimensions, each having their own 100 character limit.

Custom Events

Custom events differ from custom dimensions as they signify that a particular action has occured. The following is an illustrative examples of what might be considered a custom event:

• A User Logged In

• A User Purchased a Product

• A User was Presented with a Paywall

• A User was Asked to Subscribe

• A User unlocked an Achievement

Custom Event Properties

A custom event may have some properties associated with it. These properties are treated as string values. For example, if your custom event was "purchased_product", a custom property might by "product_sku" with a value of "123456".

Reserved Properties / Metrics

In addition to custom properties, there are a set of properties which, when provided, will act as custom metrics. These reserved properties will not be treated as strings and must contain only numeric values.

List of reserved properties:

Adding Custom Events

To add a custom event you will call a javascript function from the Gamera on page library at the time the event occurs on your site. The following examples demonstrate how to use custom events:

Example 1 - Custom event with custom properties

window.gamera = window.gamera || {};
window.gamera.cmd = window.gamera.cmd || [];
window.gamera.cmd.push(function() {
    window.gamera.event("my-custom-event", {
        "property-1": "test-value",
        "property-2": "value1,value2,value3",
        "score": 99
    });
});

Example 2 - Tracking a user funnel

window.gamera = window.gamera || {};
window.gamera.cmd = window.gamera.cmd || [];
window.gamera.cmd.push(function() {
    window.gamera.event("email_subscription_offered");
    // or
    window.gamera.event("email_subscription_accepted");
    // or
    window.gamera.event("email_subscription_rejected");
});

Milestones

Milestones are significant events that occur during the lifecycle of your business which you would like to correlate against performance. For example, let's say that you just released a significant new layout to your website, and wanted to observe your core web vitals performance before and after the release. In the screenshot below, you can see this example in action:

How to create a milestone

Milestones can be created simply by sending your values to an HTTP Get request (web request) at the following url:  https://portal.gamera.app/api/sites/mysite.com/milestones

The following URL Parameters are supported:

A more complete example is available below:

https://portal.gamera.app/api/sites/mysite.com/milestones?token=<my_api_token>&label=Introducing%20Gamera%20Milestones&labelURL=https://github.com/my/release/url

Generating a milestones API token

To send milestone events to gamera you will need an API token. To retrieve or generate a new API token please follow these steps:

1. Select Site Manager from the left hand navigation menu

2. Find the site you wish to generate an API key for

3. Click the right hand actions menu (3 vertical dots)

4. Select Manage API Key
   

   

5. Select Generate New API Key or copy the existing API key