android-components/components/service/nimbus

Android Components > Service > Nimbus

A wrapper for the Nimbus SDK.

Contents:

• Usage

Usage

Setting up the dependency

Use Gradle to download the library from maven.mozilla.org (Setup repository):

implementation "org.mozilla.components:service-nimbus:{latest-version}"

Initializing the Experiments library

TODO

Updating of experiments

TODO

Checking if a user is part of an experiment

TODO

Testing Nimbus

This section contains information about the Kinto and UI schemas needed to set up and run experiments on the "Dev" Kinto instance located at https://kinto.dev.mozaws.net. NOTE The dev server instance requires LDAP authorization, but does not require connection to the internal Mozilla VPN.

Where to add the Kinto and UI schemas

For testing purposes, create a collection with an id of nimbus-mobile-experiments in the main bucket on the Kinto dev server.

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "$id": "http://mozilla.org/example.json",
  "type": "object",
  "title": "Nimbus Schema",
  "description": "This is the description of the current Nimbus experiment schema, which can be found at https://github.com/mozilla/nimbus-shared",
  "default": {},
  "examples": [
    {
      "slug": "secure-gold",
      "endDate": null,
      "branches": [
        {
          "slug": "control",
          "ratio": 1
        },
        {
          "slug": "treatment",
          "ratio": 1
        }
      ],
      "probeSets": [],
      "startDate": null,
      "application": "org.mozilla.fenix",
      "bucketConfig": {
        "count": 100,
        "start": 0,
        "total": 10000,
        "namespace": "secure-gold",
        "randomizationUnit": "nimbus_id"
      },
      "userFacingName": "Diagnostic test experiment",
      "referenceBranch": "control",
      "isEnrollmentPaused": false,
      "proposedEnrollment": 7,
      "userFacingDescription": "This is a test experiment for diagnostic purposes.",
      "id": "secure-gold"
    }
  ],
  "required": [
    "slug",
    "branches",
    "application",
    "bucketConfig",
    "userFacingName",
    "referenceBranch",
    "isEnrollmentPaused",
    "proposedEnrollment",
    "userFacingDescription",
    "id"
  ],
  "properties": {
    "slug": {
      "$id": "#/properties/slug",
      "type": "string",
      "title": "Slug",
      "description": "The slug is the unique identifier for the experiment.",
      "default": "",
      "examples": ["fenix-search-widget-experiment"]
    },
    "endDate": {
      "$id": "#/properties/endDate",
      "type": ["string", "null"],
      "format": "date-time",
      "title": "End Date",
      "description": "This is the date that the experiment will end.",
      "default": null,
      "examples": [null]
    },
    "branches": {
      "$id": "#/properties/branches",
      "type": "array",
      "title": "Branches",
      "description": "Branches relate to the specific treatments to be applied for the experiment.",
      "default": [],
      "examples": [
        [
          {
            "slug": "control",
            "ratio": 1
          },
          {
            "slug": "treatment",
            "ratio": 1
          }
        ]
      ],
      "additionalItems": true,
      "items": {
        "$id": "#/properties/branches/items",
        "anyOf": [
          {
            "$id": "#/properties/branches/items/anyOf/0",
            "type": "object",
            "title": "Branch Items",
            "description": "Each branch has a slug, or name, and a ratio that weights selection into that branch",
            "default": {},
            "examples": [
              {
                "slug": "control",
                "ratio": 1
              }
            ],
            "required": ["slug", "ratio"],
            "properties": {
              "slug": {
                "$id": "#/properties/branches/items/anyOf/0/properties/slug",
                "type": "string",
                "title": "Branch Slug",
                "description": "The branch slug is the unique name of the branch, within this experiment.",
                "default": "control",
                "examples": ["control"]
              },
              "ratio": {
                "$id": "#/properties/branches/items/anyOf/0/properties/ratio",
                "type": "integer",
                "title": "Branch Ratio",
                "description": "This is the weighting of the branch for branch selection.",
                "default": 1,
                "examples": [1]
              }
            },
            "additionalProperties": true
          }
        ]
      }
    },
    "probeSets": {
      "$id": "#/properties/probeSets",
      "type": "array",
      "title": "Probe Sets",
      "description": "Currently unimplemented/used",
      "default": [],
      "examples": [[]],
      "additionalItems": true,
      "items": {
        "$id": "#/properties/probeSets/items"
      }
    },
    "startDate": {
      "$id": "#/properties/startDate",
      "type": ["string", "null"],
      "format": "date-time",
      "title": "Start Date",
      "description": "The date that the experiment will start",
      "default": null,
      "examples": [null]
    },
    "application": {
      "$id": "#/properties/application",
      "type": "string",
      "title": "Application",
      "description": "This is the application to target",
      "default": "",
      "examples": [
        "org.mozilla.fenix",
        "org.mozilla.firefox",
        "org.mozilla.ios.firefox"
      ]
    },
    "bucketConfig": {
      "$id": "#/properties/bucketConfig",
      "type": "object",
      "title": "Bucket Configuration",
      "description": "This is the configuration of the bucketing for determining the experiment sample size",
      "default": {},
      "examples": [
        {
          "count": 2000,
          "start": 0,
          "total": 10000,
          "namespace": "performance-experiments",
          "randomizationUnit": "nimbus_id"
        }
      ],
      "required": ["count", "start", "total", "namespace", "randomizationUnit"],
      "properties": {
        "count": {
          "$id": "#/properties/bucketConfig/properties/count",
          "type": "integer",
          "title": "Count",
          "description": "The total count of buckets to assign to be eligible to enroll in the experiment.",
          "default": 0,
          "examples": [2000]
        },
        "start": {
          "$id": "#/properties/bucketConfig/properties/start",
          "type": "integer",
          "title": "Starting Bucket",
          "description": "This is the bucket that the count of buckets will start from.",
          "default": 0,
          "examples": [0]
        },
        "total": {
          "$id": "#/properties/bucketConfig/properties/total",
          "type": "integer",
          "title": "Total Buckets",
          "description": "This is the total number of buckets to divide the population into for enrollment purposes.",
          "default": 10000,
          "examples": [10000]
        },
        "namespace": {
          "$id": "#/properties/bucketConfig/properties/namespace",
          "type": "string",
          "title": "Namespace",
          "description": "This is the bucket namespace and should always match the experiment slug",
          "default": "",
          "examples": ["secure-gold"]
        },
        "randomizationUnit": {
          "$id": "#/properties/bucketConfig/properties/randomizationUnit",
          "type": "string",
          "title": "Randomization Unit",
          "description": "This is the id to use for randomization for the purpose of bucketing. Currently only nimbus_id implemented.",
          "default": "nimbus_id",
          "examples": ["nimbus_id"]
        }
      },
      "additionalProperties": true
    },
    "userFacingName": {
      "$id": "#/properties/userFacingName",
      "type": "string",
      "title": "User Facing Name",
      "description": "The user-facing name of the experiment.",
      "default": "",
      "examples": ["Diagnostic test experiment"]
    },
    "referenceBranch": {
      "$id": "#/properties/referenceBranch",
      "type": "string",
      "title": "Reference Branch",
      "description": "Not currently implemented, do not change default",
      "default": "control",
      "examples": ["control"]
    },
    "isEnrollmentPaused": {
      "$id": "#/properties/isEnrollmentPaused",
      "type": "boolean",
      "title": "Enrollment Paused",
      "description": "True if the enrollment is paused, false if enrollment is active.",
      "default": false,
      "examples": [false]
    },
    "proposedEnrollment": {
      "$id": "#/properties/proposedEnrollment",
      "type": "integer",
      "title": "Proposed Enrollment",
      "description": "The length in days that enrollment is proposed.",
      "default": 7,
      "examples": [7]
    },
    "userFacingDescription": {
      "$id": "#/properties/userFacingDescription",
      "type": "string",
      "title": "User Facing Description",
      "description": "This is the description of the experiment that would be presented to the user.",
      "default": "",
      "examples": ["This is a test experiment for diagnostic purposes."]
    },
    "id": {
      "$id": "#/properties/id",
      "type": "string",
      "title": "ID",
      "description": "An analog of the slug? Not sure, make this match slug...",
      "default": "",
      "examples": ["secure-gold"]
    }
  },
  "additionalProperties": true
}

UI Schema

{
  "ui:order": [
    "slug",
    "userFacingName",
    "userFacingDescription",
    "application",
    "startDate",
    "endDate",
    "bucketConfig",
    "branches",
    "referenceBranch",
    "isEnrollmentPaused",
    "proposedEnrollment",
    "id",
    "probeSets"
  ],
  "userFacingDescription": {
    "ui:widget": "textarea"
  },
  "bucketConfig": {
    "ui:order": ["start", "count", "total", "namespace", "randomizationUnit"]
  },
  "branches": {
    "ui:order": ["slug", "ratio"]
  }
}

License

This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/