# Analytics Providers

Analytics providers are the Marfeel standard for all: custom, core and AMP analytics extensions.

Mediagroup Compatibility

The new analytics providers are only available for mediagroups with XP as a Library.

Analytics providers share the same characteristics as other providers. They are declared for each tenant in their own resource file: analytics.json.

Entirely decoupled from Marfeel Core, they are published as Node packages (opens new window) from independent repositories and implemented using Typescript (opens new window).

Like other providers, a local playground is available to easily test any provider, and every implementation follows strict quality requirements by passing an Acid tests suite.

# Find an Analytics Provider

Analytics Providers are published in the Marfeel releases repository (opens new window) and can be found by looking for analytics-providers-* packages: here (opens new window).

The source code repository for each provider is named exactly like the package, eg. Marfeel/analytics-providers-googleanalytics (opens new window).

# Repository Structure

Unlike legacy metrics providers, the analytics providers must contain several files in addition to their Typescript implementation:

# Package setup

Analytics providers are Node packages, which means they always come with the minimum files required to be published:

package.json contains the package configuration and the information required to publish the analytics provider.
README.md contains a short description of the provider and instructions on how to use, debug and publish it.

# Implementation and Unit Tests

A provider's implementation has only one entry point, which must be unit tested:

src/index.ts is the entry point of the Typescript implementation.
src/index.test.ts contains unit tests for the entry point.

Additional files can be created.

# Schema

All Providers at Marfeel come with a schema. The schema defines how the provider can be used in the analytics.json. The schema also contains useful defaults, such as the default triggers of the provider.

The schema folder of an analytics provider must always include at least 2 tests, giving examples of valid and invalid usages.

schema/index.json contains the JSON schema used to validate the analytics provider on analytics.json.
schema/test/valid/index.test.json contains a valid test for the analytics provider JSON schema (There could have move tests to cover all scenarios but at least 1 is necessary).
schema/test/wrong/index.test.json contains a wrong test for the analytics provider JSON schema (There could have move tests to cover all scenarios but at least 1 is necessary).

Analytics Schema at Marfeel must use the AMP data model (opens new window) as base, and be extended if necessary to add the support for Marfeel Touch configuration.

WARNING

It is mandatory that all implementations match the AMP Schema, when it exists.

# Custom providers

When a provider is specific for a tenant, always include the field "customAnalytics": true in the top level of the schema.

For example: analytics-providers-nameofanalytic-tenantName

{
  "$id": "#nameOfAnalyticProvider",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Title for this metric",
  "description": "Some description",
  "customAnalytics": true
}

This way, the provider won't be visible in the "Add Provider" view of the Metrics screen in Marfeel Studio.

TIP

MarfeelStudio

Always set the default __extends on the schema with the path to the default triggers in MarfeelXP. A provider without this default extension cannot be configured properly through MarfeelStudio.

For example with Google analytics:

{
  "googleanalytics": [
      {
          "vars": {
              "account": "UA-XXXXXX-1"
          },
          "triggers": {
              "__extends": "marfeel/index/resources/analytics/triggers/googleanalytics/pageview.json"
          }
      }
  ]
}

# Extractor

All providers at Marfeel come with an extractor. It allows the automatic detection of the provider by MarfeelAlfred (opens new window) at tenant scaffold-time.

The extractor folder contains a Typescript implementation and unit tests:

extractor/index.ts is the entry point of the extractor.
extractor/index.test.ts contains the unit tests of the extractor

TIP

# AMP implementation

All analytics providers must be AMP-compatible.

In the best case scenario, the provider is already a listed vendor (opens new window), and following AMP's configuration schema is the only thing to do.

If the provider does not have a standard AMP implementation yet, or uses the pixel approach, you must create a custom JSP file in MarfeelXP. Create the JSP under the AMP theme: MarfeelXP/Tenants/vhosts/marfeel/themes/amp/analytics/providername.jsp. Write AMP-compatible code following the documentation of the analytic system for AMP.

# Triggers

Each analytics provider must offer a default set of triggers for AMP and Touch. This way, developer who need to use a provider never have to re-write the basic triggers, such as pageview, when they need them.

See for example Google Analytic's pageview default triggers (opens new window). Create a new default pageview trigger (both AMP and Touch) for any provider you create, in this MarfeelXP folder (opens new window).

Any provider added to a tenant via MarfeelStudio Metrics panel extends from this default trigger, provided the schema was written as expected.

# Available Scripts

NPM Script	Action	Providers CLI
`npm run build`	Builds the provider implementation and extractor	`npx provider-cli build -p`
`npm run lint`	Runs the linter	`npx provider-cli lint`
`npm run test`	Runs unit tests	`npx provider-cli test -c='./node_modules/@marfeel/analytics-providers-cli/'`
`npm run acid-tests`	Runs ACID tests	`npx provider-cli test --configs-path='./node_modules/@marfeel/analytics-providers-acid-tests'`
`npm run deploy`	Deploys provider	`npx provider-cli deploy`
`npm run build:playground`	Build playground	`npx provider-cli docs:build --configs-path='./node_modules/@marfeel/analytics-providers-playground/' --statics-path='./node_modules/@marfeel/analytics-providers-playground/public/'`
`npm run start`	Builds and runs playground	`npx provider-cli start --configs-path='./node_modules/@marfeel/analytics-providers-playground/' --statics-path='@marfeel/analytics-providers-playground/public'`

Some advanced actions can only be run using provider-cli:

Providers CLI	Action
`npx provider-cli test:schema`	Validates schema

← analytics.json metrics.json →