Measurements

What is the purpose of Measurements?

Measurements is a new method for importing data into Piano Analytics. It allows you to add context to analytical data and put it into perspective.

In this example, we put the evolution of sales from Facebook into perspective with the evolution of the number of subscribers on the Facebook page, in order to identify whether the increase is significant.

How do you define a Measurement?

A Measurement is :

• Numerical: the information must be represented by a value, such as the number of Facebook subscribers.
• Linked to a time period. A date must be associated with the value, which can be the number of subscribers per day, hour, etc.
• Aggregated data: it's important that this data is global, like the number of Facebook subscribers.

Now, if we want to have information for each user and know whether they are a Facebook subscriber, the Measurement product would no longer fit the bill, as we'd be dealing with granular data, not necessarily linked to a temporal or even numerical basis. We do, however, offer data enrichment solutions to meet this need.

What can a Measurement contain?

We've just seen that a Measurement is numerical data, but it's also possible to use properties to qualify it. To illustrate, let's take an example: I want to import weather data to see if it can have an impact on analytical data. Here we have a temperature, which is an aggregated, numerical value linked to a time period. However, limiting ourselves to one temperature per day is not very relevant, as the information is not sufficiently qualified. So we're going to improve our Measurement by adding properties:

• Country and region: here I'm going to use two standard Piano Analytics properties to give me more precise data. In France, for example, there's a big meteorological difference between mainland France and the French overseas departments and territories. But also, this is what will enable me to combine the analytical data and the Measurements data, as these values will also serve as a reconciliation key and enable me to have in one analysis the number of visits from Nouvelle-Aquitaine with the temperature of Nouvelle-Aquitaine.
• Weather report: This information doesn't exist in Piano Analytics, so I'll have to create a custom property that I'll use in my Measurement to pass on the day's weather as well as the temperature. This will include information such as "Rainy", "Sunny" etc.
• Temporality: Here I have the choice in my Measurement of obtaining information by the day or by the hour. I can import historical data, i.e. data from the previous year, but also data from the present, such as the current hour's temperature. But I can also import data into the future with weather forecasts.

Where to analyze Measurement data

When you create and send Measurement data, you create one or more metrics and send data via properties. Wherever this information is available, the Measurement data in question will be available in Explorer, Data Query, Workspaces and so on.

However, as these data are based on metrics, they are not available in Data Flow or Data Sharing.

Does my Measurement have to be linked to analytics?

You don't have to have a Measurement to extend the analytics domain. Some Measurements can operate independently, but it's a good idea to include them in the Piano Analytics interface to simplify reporting.

Do you have any examples of Measurements?

Measurements can be used in many different situations. All you need is access to the data (via API or exports) to send it to Piano Analytics. To help you, here is a non-exhaustive list of examples:

• Podcast tracking: you can import playback data from Spotify, iTunes, Deezer etc.
• Number of social network subscribers
• Analytical targets: Import sales targets to compare current sales with your target.
• Weather information
• In-store sales
• Offline campaigns, e.g. retrieve number of emails sent
• Import history from third-party tools (Google Analytics)
• Data from Google Search Console

Measurement creation

Once in the Measurement interface accessible from Data Management, simply click on the "+" button in the bottom right-hand corner to initiate Measurement creation.

The following panel will open:

The first block of general information contains :

The initial information on the display label and description is there for easy retrieval in the interface; you can add the information of your choice and even modify it later.

In the configuration section, you'll find the information you need to make the Measurement work properly:

• The display label, so you can find it in the interface
• Description to provide context
• Scope: two options are available, site or organization. When a Measurement is set to organizational scope, this means that the same information will be replicated regardless of the site selected in the interface. For example, for the weather, this is the ideal scope. Site scope corresponds to a Measurement that will have different values depending on the site(s) selected for analysis. For example, a Measurement with analytical objectives such as sales will often be on site scope, as the objectives may be different from one site to another.
• Categories are used to classify the Measurement in order to understand what it contains. This information has no impact on operation, and can be modified at a later date.
• The granularity determines the time period you are interested in for your Measurement. This depends on the data at your disposal, which can be monthly, daily or hourly.

In the configuration insert, this is the information required for the Measurement to function correctly:

• Measurement key: this will be used to send data, and is the value that will be used to identify the Measurement that will receive the data.
• The value: there may be several of these, all the values you wish to send. For example, let's imagine a "Weather" Measurement and you want to send the temperature as well as the humidity, you'll create two values, one for the temperature and the other for the humidity.

Once configured, you can press the code symbol to see what the object to be used for sending data will look like:

Note that the properties will have to be replaced by the properties of your choice, e.g. for the weather you can use the Country property and the Region property to send the weather more precisely. No configuration is required for this step.

Creating associated metrics

Once the Measurement has been created, it is necessary to create one or more metrics to be able to use it in our interfaces. Simply click on the Associated metrics tab on the side panel and click on the New metric button.

The following fields will be available:

• Display label: this is the name of your metric, which you can modify later.
• Description, you can explain your metric in a few words so that everyone understands what it represents
• MetricKey, this is the technical information required to use your metric via our API
  Display type, important for formatting the metric
  Precision, when the display type can be decimal, you can select the number of digits after the decimal point
• Time aggregation, to explain this it's best to use an example. Let's imagine you send the value 2000 on Monday, then the value 1000 on Tuesday. In your analysis interface, you select a period containing Monday and Tuesday. Time aggregation will define the expected result: is it a sum and you want to obtain 3000? Ideal when the information is summable, such as sales. Would you prefer an average? Ideal for information such as weather and temperature.
• Aggregation on properties, when you've added property information to your Measurement to better qualify it, what information should be returned if you don't select that property when analyzing a Measurement-based metric. Should we sum the information? Average them? etc.
• Visibility, i.e. whether the metric should be visible to everyone, or only to its creator.

How do I send data to Measurements?

You can find all the information you need in our developer documentation, available here.

Complete Example: Google Search Console

Google Search Console (GSC) data helps understand how a website performs within the Google ecosystem, but often these data are analyzed separately without being cross-referenced with other data like analytics. With Measurements, you can import GSC data into Piano Analytics and perform new analyses. Let’s walk through the steps needed to create this Measurement.

Preparing the Measurement

The first step is to think about the data you want to import in order to define the actions to be taken.

In our case, we want to retrieve GSC data by devices, URLs, and also get the keywords. As for the metrics, we are interested in the number of impressions, clicks, and the average position.

Let’s proceed with the creation of the Measurement by following the previously presented methodologies. We’ll create a Measurement at the organization level since the definition of a site might differ between GSC and Piano Analytics. However, if the definition is the same between the two, it’s recommended to create a site-level Measurement. The granularity will be set to daily to import our data on a daily basis.
For the Measurement key, we’ll use "gsc", and we will create three value keys (corresponding to the metrics we want to measure): impressions, clicks, and position.

For the properties, we’ll use two standard properties: device_type for device information and event_url for URLs. Regarding keywords, we will need to create a custom property that we will call "gsc_keyword", which will be of type array because multiple values can be returned for a single URL by Google.

Once the Measurement and the custom property are created, we can move to the next step.

Retrieving the Data

Before sending the data, it is necessary to retrieve them. There are several options available, and you are free to choose the one you prefer:

• Use a third-party tool specialized in data retrieval, such as Adverity. The advantage of this solution is that the partner keeps the connections up to date, so we don’t have to monitor changes in GSC’s retrieval methods, as that will be handled by the partner. Additionally, retrieving this data is very easy and can be done in just a few clicks.
• Download flat files like CSVs directly from GSC.
• Use the GSC API.

Regardless of the method chosen, the data will be the same. An additional step is needed to clean the data to ensure the values match between the Measurement and the analytics data so they can be cross-referenced. For instance, pay attention to URLs and make sure the same rules are applied, as well as for devices. Since Google and Piano Analytics do not use the same detection base, discrepancies may occur. For example, Google may return "Mobile" while Piano Analytics may return "Mobile Phone", so it’s necessary to harmonize these values to have "Mobile Phone" in both datasets.

Now that we have all this information, we can proceed to retrieve the data and move on to the next step.

Sending the Data

To send data to a Measurement, you must use the dedicated API. Using our example, here is a JSON object we could send via the API:

It includes all the information declared in the interface, as well as the properties we want to populate (which we selected in the first step).

All that remains is to call the Measurement API daily to keep the data up to date in Piano Analytics.

Technical Setup

There are many options to programmatically retrieve and send data. Here are two scenarios:

• In Adverity, retrieve data from GSC and harmonize the values in device_type to match those in Piano Analytics. Deposit this data into an Amazon bucket.
  Create a JavaScript script that runs via an Amazon Lambda to retrieve the file from the Amazon bucket, transform it into a JSON file compatible with the Measurement API, and send it.
• From Google Apps Script, create a script that calls the GSC API and harmonizes the device_type values. Format the data into a JSON file for the Measurement API and then send it.

Of course, these are just two examples, but you can implement the infrastructure of your choice based on your preferences.

I sent the wrong value, how can I fix it?

When you sent a wrong value, for instance for the Measurement Weather with the property Country and the value France you sent 301 degrees instead of 30.1. You can send the value again and specify the 30.1 and it will replace the 301 in the Measurement. 

How much time should I wait before seeing the data in the interface?

Usually it is a matter of seconds before seeing in the interface. Nevertheless, we have some cache to improve performance, meaning that sometimes you will need to wait the cache to be cleared to see your data (especially for update). This cache is cleared every hour. 

How many values can I put in a Measurements?

You can send up to 100k different values per day. For instance, if you send your Measurements with the properties Page, you can send 100k different values for the page per day. 

Can I use every properties in Measurements?

Some properties are part of a blacklist as they granularity is too fine. 

• event_time
• event_time_utc
• hit_time_utc
• device_timestamp_utc
• visit_id
• visit_time
• visitor_id
• app_sessionid
• av_session_id
• av_session_time
• av_session_time_utc
• rm_session_id
• transaction_id
• cart_id
• user_id
• event_id
• av_duration
• av_cursor_difference
• page_duration
• event_duration
• event_position
• visit_duration
• visit_page_views
• visit_sales
• rm_last_duration
• av_buffer_duration
• av_content_duration
• page_position
• src_url
• src_url_full
• rm_content_duration
• av_playback_duration
• av_rebuffer_duration
• rm_playback_duration
• av_buffer_total_duration
• av_content_duration_range
• av_playback_total_duration
• av_rebuffer_total_duration
• av_session_content_duration
• date
• date_week
• date_yearofweek
• date_month
• date_day
• date_year
• date_monthnumber
• date_daynumber
• date_firstdateofweek
• date_firstdateofmonth
• event_second
• visit_second
• evo_second
• event_minute
• visit_minute
• evo_minute
• event_hour
• visit_hour
• evo_hour
• evo_day