Recording product attribution and distribution

The Glean SDKs support the reporting of product attribution (the source and context that may have led a person to choose the product) and product distribution (the name and context of partners distributing the product on our behalf) in all pings that contain a client_info. The Glean SDK has no means to determine this itself, so it relies on products setting and keeping these values up-to-date via general APIs.

Recording API

updateAttribution

Updates the values sent in the client_info.attribution section.

Glean.updateAttribution(AttributionMetrics(
  source = "google-play",
  medium = "organic",
  campaign = "mozilla-org",
  term = "browser with developer tools for android",
  content = "firefoxview",
))

Glean.shared.updateAttribution(AttributionMetrics(
  source: "google-play",
  medium: "organic",
  campaign: "mozilla-org",
  term: "browser with developer tools for android",
  content: "firefoxview",
))

from glean import Glean
from glean.metrics import AttributionMetrics

Glean.update_attribution(AttributionMetrics(
  source="google-play",
  medium="organic",
  campaign="mozilla-org",
  term="browser with developer tools for android",
  content="firefoxview",
))

glean::update_attribution(AttributionMetrics {
  source: Some("google-play".into()),
  medium: Some("organic".into()),
  campaign: Some("mozilla-org".into()),
  term: Some("browser with developer tools for android".into()),
  content: Some("firefoxview".into()),
});

C++

C++ is not presently supported.

JavaScript

Services.fog.updateAttribution(
  "google-play" /* aSource */,
  "organic" /* aMedium */,
  "mozilla-org" /* aCampaign */,
  "browser with developer tools for android" /* aTerm */,
  "firefoxview" /* aContent */);

Limits

  • Each AttributionMetrics field inherits the limits of a string metric.
  • String values must not exceed 255 bytes of UTF-8. Longer strings will be truncated.
    • Prior to Glean v60.4.0 the limit was 100 bytes.

Recorded errors

  • Each AttributionMetrics field may report errors like string metrics do.
  • invalid_overflow:
    • If the string value is too long. (Prior to Glean v31.5.0 this was recorded as invalid_value.)
  • invalid_type:
    • If a non-string value is provided.

updateDistribution

Updates the value sent in the client_info.distribution section.

Glean.updateDistribution(DistributionMetrics(
  name = "MozillaOnline",
))

Glean.shared.updateDistribution(DistributionMetrics(
  name: "MozillaOnline",
))

from glean import Glean
from glean.metrics import DistributionMetrics

Glean.update_attribution(DistributionMetrics(
  name="MozillaOnline",
))

glean::update_attribution(DistributionMetrics {
  name: Some("MozillaOnline".into()),
});

C++

C++ is not presently supported.

JavaScript

Services.fog.updateDistribution("MozillaOnline" /* aName */);

Limits

  • Each DistributionMetrics field inherits the limits of a string metric.
  • String values must not exceed 255 bytes of UTF-8. Longer strings will be truncated.
    • Prior to Glean v60.4.0 the limit was 100 bytes.

Recorded errors

  • Each DistributionMetrics field may report errors like string metrics do.
  • invalid_overflow:
    • If the string value is too long. (Prior to Glean v31.5.0 this was recorded as invalid_value.)
  • invalid_type:
    • If a non-string value is provided.

Testing API

testGetAttribution

Returns the current values of Attribution fields.

import org.junit.Assert.assertEquals

assertEquals(AttributionMetrics(
  source: "google-play",
  medium: "organic",
  campaign: "mozilla-org",
  term: "browser with developer tools for android",
  content: "firefoxview",
), Glean.testGetAttribution())

XCTAssertEqual(AttributionMetrics(
  source: "google-play",
  medium: "organic",
  campaign: "mozilla-org",
  term: "browser with developer tools for android",
  content: "firefoxview",
), Glean.shared.testGetAttribution())

from glean import Glean
from glean.metrics import AttributionMetrics

assert AttributionMetrics(
  source="google-play",
  medium="organic",
  campaign="mozilla-org",
  term="browser with developer tools for android",
  content="firefoxview") == Glean.test_get_attribution()

assert_eq!(AttributionMetrics {
  source: Some("google-play".into()),
  medium: Some("organic".into()),
  campaign: Some("mozilla-org".into()),
  term: Some("browser with developer tools for android".into()),
  content: Some("firefoxview".into()),
}, glean::test_get_attribution());

C++

C++ is not presently supported.

JavaScript

const expected = {
  source: "google-play",
  medium: "organic",
  campaign: "mozilla-org",
  term: "browser with developer tools for android",
  content: "firefoxview",
};
Assert.deepEqual(expected, Services.fog.testGetAttribution());

testGetDistribution

Returns the current values of Distribution fields.

import org.junit.Assert.assertEquals

assertEquals(DistributionMetrics(
  name: "MozillaOnline",
), Glean.testGetDistribution())

XCTAssertEqual(DistributionMetrics(
  name: "MozillaOnline",
), Glean.shared.testGetDistribution())

from glean import Glean
from glean.metrics import DistributionMetrics

assert DistributionMetrics(name="MozillaOnline") == Glean.test_get_distribution()

assert_eq!(DistributionMetrics {
  name: Some("MozillaOnline".into()),
}, glean::test_get_distribution());

C++

C++ is not presently supported.

JavaScript

const expected = {
  name: "MozillaOnline",
};
Assert.deepEqual(expected, Services.fog.testGetDistribution());

Extending product attribution and distribution

In addition to the fields in these APIs, products may also define and record extended product attribution and distribution information in two object metrics:

  • glean.attribution.ext, and
  • glean.distribution.ext.

These metrics are different from normal object metrics:

  • They are defined by products, even though they use the reserved glean metric category
  • Columns for their data in datasets are in client_info instead of in metrics.object
    • Specifically, client_info.attribution.ext and client_info.distribution.ext

These metrics are different from other product attribution and distribution fields:

  • Their structure and contents will differ from product to product
  • They will only be present in pings defined in their metric definitions
  • Their lifetime might not be user, so they may not have values in all pings they are defined to be sent in

Otherwise, they are defined, recorded to, tested, and consumed like typical object metrics.

Reference