### CLI Configuration Example

Source: https://github.com/mozilla/application-services/blob/main/examples/nimbus/README.md

Example structure for the CLI configuration file. Customize server details and collection names as needed.

```json
{
    "context": {..},// App context elements
    "server_url": "...", // A remote settings url
    "bucket_name": "..." // Name of the bucket in the remote server (Defaults to `main`)
    "collection_name": "...", // Name of a collection in the remote server (Defaults to `messaging-experiment`)
    "uuid": ".." // A custom uuid to use
}
```

--------------------------------

### Install mdbook and related tools

Source: https://github.com/mozilla/application-services/blob/main/docs/adding-docs.md

Installs the mdbook tool and necessary extensions for building documentation. Ensure you have Rust and Cargo installed.

```sh
cargo install mdbook mdbook-mermaid mdbook-open-on-gh
```

--------------------------------

### Ads Client Configuration Example

Source: https://github.com/mozilla/application-services/blob/main/components/ads-client/docs/usage-swift.md

Demonstrates how to configure and build the ads client with custom cache and telemetry settings.

```swift
let cache = MozAdsCacheConfig(
    dbPath: "/tmp/ads_cache.sqlite",
    defaultCacheTtlSeconds: 600,   // 10 min
    maxSizeMib: 20                 // 20 MiB
)

let telemetry = AdsClientTelemetry()

let client = MozAdsClientBuilder()
    .environment(environment: .prod)
    .cacheConfig(cacheConfig: cache)
    .telemetry(telemetry: telemetry)
    .build()
```

--------------------------------

### Ads Client Configuration Example

Source: https://github.com/mozilla/application-services/blob/main/components/ads-client/docs/usage-kotlin.md

Demonstrates how to configure and build the `MozAdsClient` using `MozAdsClientBuilder`, `MozAdsCacheConfig`, and `AdsClientTelemetry`.

```kotlin
val cache = MozAdsCacheConfig(
    dbPath = "/tmp/ads_cache.sqlite",
    defaultCacheTtlSeconds = 600L,   // 10 min
    maxSizeMib = 20L                 // 20 MiB
)

val telemetry = AdsClientTelemetry()

val client = MozAdsClientBuilder()
    .environment(MozAdsEnvironment.PROD)
    .cacheConfig(cache)
    .telemetry(telemetry)
    .build()
```

--------------------------------

### Ads Client Configuration Example

Source: https://github.com/mozilla/application-services/blob/main/components/ads-client/docs/usage-javascript.md

Demonstrates how to configure the Ads Client with environment, cache, and telemetry settings. This example shows setting a custom cache TTL and size, and providing a telemetry instance.

```javascript
const cache = MozAdsCacheConfig({
    dbPath: "/tmp/ads_cache.sqlite",
    defaultCacheTtlSeconds: 600,   // 10 min
    maxSizeMib: 20                 // 20 MiB
});

const telemetry = new AdsClientTelemetry();

const client = MozAdsClientBuilder()
    .environment(MozAdsEnvironment.Prod)
    .cacheConfig(cache)
    .telemetry(telemetry)
    .build();
```

--------------------------------

### UnifiedComplete Example

Source: https://github.com/mozilla/application-services/blob/main/components/places/README.md

Shows an example of using UnifiedComplete for auto-complete functionality.

```javascript
UnifiedComplete.something("example.co")
```

--------------------------------

### OHTTP Usage Example

Source: https://github.com/mozilla/application-services/blob/main/components/ads-client/docs/usage-swift.md

Demonstrates how to make ad requests and record callbacks over OHTTP. Ensure OHTTP is configured at the viaduct level.

```swift
// Request ads over OHTTP
let ads = try client.requestTileAds(mozAdRequests: placements, options: MozAdsRequestOptions(ohttp: true))

// Record a click over OHTTP
try client.recordClick(clickUrl: ad.callbacks.click, options: MozAdsCallbackOptions(ohttp: true))

// Record an impression over OHTTP
try client.recordImpression(impressionUrl: ad.callbacks.impression, options: MozAdsCallbackOptions(ohttp: true))
```

--------------------------------

### Example: Test JEXL Version Comparison

Source: https://github.com/mozilla/application-services/blob/main/components/support/nimbus-cli/README.md

Demonstrates using JEXL to test version comparison against the application version.

```sh
# Test version comparison
nimbus-cli --app firefox_ios --channel beta eval-jexl "app_version|versionCompare('120.0') >= 0"
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/mozilla/application-services/blob/main/tools/README.md

Installs Python dependencies from the requirements.txt file. Ensure you are in the tools directory and have pip3 installed.

```bash
pip3 install --require-hashes -r ./tools/requirements.txt
```

--------------------------------

### Install Maven on WSL

Source: https://github.com/mozilla/application-services/blob/main/docs/building.md

Install Maven using apt on a WSL environment. This is a prerequisite for configuring the Maven settings.

```bash
sudo apt install maven
```

--------------------------------

### Firebase Configuration Example

Source: https://github.com/mozilla/application-services/blob/main/components/push/README.md

Example of the content expected in the `fenix_firebase.xml` file. This file contains Firebase-specific resource values.

```xml
<resources>
    <string name="default_web_client_id" translatable="false">redacted</string>
    <string name="firebase_database_url" translatable="false">redacted</string>
    etc
</resources>

```

--------------------------------

### Clone Repository and Initialize Submodules

Source: https://github.com/mozilla/application-services/blob/main/docs/building.md

Clone the application-services repository and initialize its submodules. This is the first step before installing dependencies.

```shell
$ git clone https://github.com/mozilla/application-services # (or use the ssh link)
$ cd application-services
$ git submodule update --init --recursive
```

--------------------------------

### Install GYP on macOS

Source: https://github.com/mozilla/application-services/blob/main/docs/building.md

Installs GYP, a build system generator, on macOS. This involves downloading a bootstrap script, cloning the GYP repository, and installing it via pip.

```shell
wget https://bootstrap.pypa.io/ez_setup.py -O - | python3 -
git clone https://chromium.googlesource.com/external/gyp.git ~/tools/gyp
cd ~/tools/gyp
pip install .
```

--------------------------------

### Install NDK via Command Line

Source: https://github.com/mozilla/application-services/blob/main/components/ads-client/docs/building-locally-for-android.md

Installs the required NDK version 29.0.14206865 using the Android SDK manager. Ensure ANDROID_HOME is set correctly.

```bash
$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --install "ndk;29.0.14206865"
```

--------------------------------

### Example Ads Client Telemetry Implementation

Source: https://github.com/mozilla/application-services/blob/main/components/ads-client/docs/usage-javascript.md

An example class implementing the MozAdsTelemetry interface. This class should be extended and its methods bound to your telemetry system.

```javascript
class AdsClientTelemetry {
    recordBuildCacheError(label, value) {
        // Bind to your telemetry system
    }

    recordClientError(label, value) {
        // Bind to your telemetry system
    }

    recordClientOperationTotal(label) {
        // Bind to your telemetry system
    }

    recordDeserializationError(label, value) {
        // Bind to your telemetry system
    }

    recordHttpCacheOutcome(label, value) {
        // Bind to your telemetry system
    }
}
```

--------------------------------

### OHTTP Usage Example

Source: https://github.com/mozilla/application-services/blob/main/components/ads-client/docs/usage-javascript.md

Demonstrates how to route ad requests and callbacks through OHTTP. Ensure OHTTP is configured at the viaduct level before use.

```javascript
// Request ads over OHTTP
const ads = client.requestTileAds(placements, {
    ohttp: true
});

// Record a click over OHTTP
client.recordClick(ad.callbacks.click, { ohttp: true });

// Record an impression over OHTTP
client.recordImpression(ad.callbacks.impression, { ohttp: true });
```

--------------------------------

### AdsClientTelemetry Implementation Example

Source: https://github.com/mozilla/application-services/blob/main/components/ads-client/docs/usage-kotlin.md

Provides an example implementation of the `MozAdsTelemetry` interface using GleanMetrics.

```kotlin
import mozilla.appservices.adsclient.MozAdsTelemetry
import org.mozilla.appservices.ads_client.GleanMetrics.AdsClient

class AdsClientTelemetry : MozAdsTelemetry {
    override fun recordBuildCacheError(label: String, value: String) {
        AdsClient.buildCacheError[label].set(value)
    }

    override fun recordClientError(label: String, value: String) {
        AdsClient.clientError[label].set(value)
    }

    override fun recordClientOperationTotal(label: String) {
        AdsClient.clientOperationTotal[label].add()
    }

    override fun recordDeserializationError(label: String, value: String) {
        AdsClient.deserializationError[label].set(value)
    }

    override fun recordHttpCacheOutcome(label: String, value: String) {
        AdsClient.httpCacheOutcome[label].set(value)
    }
}
```

--------------------------------

### Install Java 8 on WSL

Source: https://github.com/mozilla/application-services/wiki/Building-the-Android-Components

Installs Oracle Java 8 using a PPA, which is required for some builds. Ensure you have the necessary permissions to run sudo commands.

```bash
sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java8-installer
sudo apt install oracle-java8-set-default
```

--------------------------------

### Set up Android SDK in WSL

Source: https://github.com/mozilla/application-services/wiki/Building-the-Android-Components

Downloads and configures the Android SDK within the WSL environment. This includes setting the ANDROID_HOME environment variable and installing necessary platforms and tools.

```bash
cd ~
mkdir android-sdk
cd android-sdk
unzip {path-to.zip}
export ANDROID_HOME=$HOME/android-sdk
$ANDROID_HOME/tools/bin/sdkmanager "platforms;android-26"
$ANDROID_HOME/tools/bin/sdkmanager --licenses
```

--------------------------------

### Install xcpretty for iOS Build

Source: https://github.com/mozilla/application-services/blob/main/docs/building.md

Install the xcpretty gem, a tool that makes Xcode build output more readable. This is required for the iOS build process.

```bash
gem install xcpretty
```

--------------------------------

### Example: Copy Deeplink to Clipboard

Source: https://github.com/mozilla/application-services/blob/main/components/support/nimbus-cli/README.md

Demonstrates evaluating a JEXL expression and copying the resulting deeplink URL to the clipboard for manual testing.

```sh
# Copy deeplink to clipboard for manual testing
nimbus-cli --app fenix --channel developer eval-jexl "is_default_browser" --pbcopy
```

--------------------------------

### Before and After Migration Example

Source: https://github.com/mozilla/application-services/blob/main/components/support/url-macro/README.md

Compares the 'before' and 'after' code patterns when migrating to the `url!` macro for static URL declarations. The 'after' version uses the macro for compile-time validation.

```rust
// Before
static MARS_API_ENDPOINT_PROD: Lazy<Url> = Lazy::new(|| {
    Url::parse("https://ads.mozilla.org/v1/").expect("hardcoded URL must be valid")
});

// After
static MARS_API_ENDPOINT_PROD: Lazy<Url> = Lazy::new(|| url!("https://ads.mozilla.org/v1/"));
```

--------------------------------

### Install Linux System Dependencies for bindgen

Source: https://github.com/mozilla/application-services/blob/main/docs/building.md

Installs the libclang development package, necessary for the bindgen tool on Linux.

```shell
apt install libclang-dev
```

--------------------------------

### Example: Evaluate Simple JEXL Expression

Source: https://github.com/mozilla/application-services/blob/main/components/support/nimbus-cli/README.md

Demonstrates evaluating a simple JEXL expression to check the locale.

```sh
# Evaluate a simple expression
nimbus-cli --app fenix --channel developer eval-jexl "locale == 'en-US'"
```

--------------------------------

### OHTTP Usage Example

Source: https://github.com/mozilla/application-services/blob/main/components/ads-client/docs/usage-kotlin.md

Demonstrates how to make ad requests and record callbacks over OHTTP. OHTTP must be configured at the viaduct level. The client automatically handles preflight requests for geo-location and user-agent headers when OHTTP is enabled.

```kotlin
// Request ads over OHTTP
val ads = client.requestTileAds(placements, MozAdsRequestOptions(ohttp = true))

// Record a click over OHTTP
client.recordClick(ad.callbacks.click, MozAdsCallbackOptions(ohttp = true))

// Record an impression over OHTTP
client.recordImpression(ad.callbacks.impression, MozAdsCallbackOptions(ohttp = true))
```

--------------------------------

### AdsClientTelemetry Implementation Example

Source: https://github.com/mozilla/application-services/blob/main/components/ads-client/docs/usage-swift.md

Provides a concrete implementation of the MozAdsTelemetry protocol for collecting ads client metrics.

```swift
import MozillaRustComponents
import Glean

public final class AdsClientTelemetry: MozAdsTelemetry {
    public func recordBuildCacheError(label: String, value: String) {
        AdsClientMetrics.buildCacheError[label].set(value)
    }

    public func recordClientError(label: String, value: String) {
        AdsClientMetrics.clientError[label].set(value)
    }

    public func recordClientOperationTotal(label: String) {
        AdsClientMetrics.clientOperationTotal[label].add()
    }

    public func recordDeserializationError(label: String, value: String) {
        AdsClientMetrics.deserializationError[label].set(value)
    }

    public func recordHttpCacheOutcome(label: String, value: String) {
        AdsClientMetrics.httpCacheOutcome[label].set(value)
    }
}
```

--------------------------------

### Install Windows Subsystem for Linux (WSL) Dependencies

Source: https://github.com/mozilla/application-services/blob/main/docs/building.md

Installs essential build tools and libraries on WSL for Windows, including unzip, python3, build-essential, zlib, and tcl-dev.

```shell
sudo apt install unzip
sudo apt install python3
sudo apt install build-essential
sudo apt-get install zlib1g-dev
sudo apt install tcl-dev
```

--------------------------------

### Verify iOS Build Environment

Source: https://github.com/mozilla/application-services/blob/main/docs/building.md

Run this script to check your iOS build setup and environment variables. Address any issues reported by the script and re-run it.

```bash
./libs/verify-ios-environment.sh
```

--------------------------------

### Verify Desktop Environment and Run Tests

Source: https://github.com/mozilla/application-services/blob/main/docs/building.md

Runs a script to check your desktop environment's dependencies and then executes cargo tests. This verifies your build setup before proceeding.

```shell
./libs/verify-desktop-environment.sh
cargo test
```

--------------------------------

### Setup NDK Standalone Toolchains

Source: https://github.com/mozilla/application-services/wiki/Building-the-Android-Components

Creates a directory for standalone NDK toolchains and sets the ANDROID_NDK_TOOLCHAIN_DIR environment variable. This is a prerequisite for building openssl and sqlcipher.

```bash
mkdir -p ~/.ndk-standalone-toolchains
export ANDROID_NDK_TOOLCHAIN_DIR=$HOME/.ndk-standalone-toolchains
```

--------------------------------

### Configure Binary Target with Local XCFramework Path

Source: https://github.com/mozilla/application-services/blob/main/docs/howtos/locally-published-components-in-firefox-ios.md

Use this configuration in the rust-components-swift Package.swift file to point to a local, unzipped XCFramework. This is part of the legacy setup.

```swift
.binaryTarget(
  name: "MozillaRustComponents",
  path: "./MozillaRustComponents.xcframework"
)
```

--------------------------------

### Android NDK Environment Setup for JNA

Source: https://github.com/mozilla/application-services/blob/main/docs/howtos/locally-building-jna.md

Configure environment variables to point to your Android NDK installation and its toolchains. Adjust paths and version numbers based on your system and NDK setup.

```bash
export NDK_ROOT="$HOME/Library/Android/sdk/ndk/28.2.13676358"
export NDK_PLATFORM="$NDK_ROOT/platforms/android-25"
export PATH="$PATH:$NDK_ROOT/toolchains/llvm/prebuilt/darwin-x86_64/bin"
export PATH="$PATH:$NDK_ROOT/toolchains/aarch64-linux-android-4.9/prebuilt/darwin-x86_64/bin"
export PATH="$PATH:$NDK_ROOT/toolchains/arm-linux-androideabi-4.9/prebuilt/darwin-x86_64/bin"
export PATH="$PATH:$NDK_ROOT/toolchains/x86-4.9/prebuilt/darwin-x86_64/bin"
export PATH="$PATH:$NDK_ROOT/toolchains/x86_64-4.9/prebuilt/darwin-x86_64/bin"
```

--------------------------------

### Install Linux System Dependencies for NSS

Source: https://github.com/mozilla/application-services/blob/main/docs/building.md

Installs system dependencies required for building NSS on Linux. Ensure gyp, ninja-build, python3, zlib, perl, and patch are installed.

```shell
apt install gyp
apt install ninja-build
apt install python3
apt install zlib1g-dev
apt install perl
apt install patch
```

--------------------------------

### Install Linux System Dependencies for SQLcipher

Source: https://github.com/mozilla/application-services/blob/main/docs/building.md

Installs the tcl package, which is required for building SQLcipher on Linux.

```shell
apt install tclsh
```

--------------------------------

### Creating a MozAdsClient Instance

Source: https://github.com/mozilla/application-services/blob/main/components/ads-client/docs/usage-kotlin.md

Use the MozAdsClientBuilder to configure and create the client with environment, cache, and telemetry settings.

```kotlin
val client = MozAdsClientBuilder()
    .environment(MozAdsEnvironment.PROD)
    .cacheConfig(cache)
    .telemetry(telemetry)
    .build()
```

--------------------------------

### Build repository documentation

Source: https://github.com/mozilla/application-services/blob/main/docs/adding-docs.md

Executes the script to build the documentation for the repository. The output will be located in the 'build/docs/book' directory.

```sh
./tools/build.docs.sh
```

--------------------------------

### Create MozAdsClient Instance

Source: https://github.com/mozilla/application-services/blob/main/components/ads-client/docs/usage-javascript.md

Use the MozAdsClientBuilder to configure and create a client instance. Set the environment, cache configuration, and telemetry before building.

```javascript
const client = MozAdsClientBuilder()
    .environment(MozAdsEnvironment.Prod)
    .cacheConfig(cache)
    .telemetry(telemetry)
    .build();
```

--------------------------------

### Install Updated NSS Version

Source: https://github.com/mozilla/application-services/blob/main/docs/howtos/upgrading-nss-guide.md

After clearing old artifacts and bumping the NSS version, run this script to install the updated version.

```bash
./libs/verify-desktop-environment.sh
```

--------------------------------

### Install macOS System Dependencies for NSS

Source: https://github.com/mozilla/application-services/blob/main/docs/building.md

Installs ninja and python using Homebrew on macOS. Verifies that python3 points to the Homebrew-installed version.

```shell
brew install ninja python
```

--------------------------------

### Run Experiments CLI

Source: https://github.com/mozilla/application-services/blob/main/examples/nimbus/README.md

Execute the CLI to display valid experiments from the server. Ensure you have the correct configuration file path.

```bash
cargo run -p examples-nimbus-experiment -- -c ./config/config.json show-experiments
```

--------------------------------

### Creating a MozAdsClient Instance

Source: https://github.com/mozilla/application-services/blob/main/components/ads-client/docs/usage-swift.md

Use the MozAdsClientBuilder to configure and create the client with a fluent API for setting options like environment, cache configuration, and telemetry.

```swift
let client = MozAdsClientBuilder()
    .environment(environment: .prod)
    .cacheConfig(cacheConfig: cache)
    .telemetry(telemetry: telemetry)
    .build()
```

--------------------------------

### List Experiments from Server

Source: https://github.com/mozilla/application-services/blob/main/components/support/nimbus-cli/README.md

Use this command to list all experiments available from a specified server. It supports optional file arguments and can utilize the v6 API for fetching recipes.

```sh
nimbus-cli --app <APP> --channel <CHANNEL> list [OPTIONS] [SERVER]
```

--------------------------------

### Firefox Android Database Size Limit

Source: https://github.com/mozilla/application-services/blob/main/docs/adr/0007-limit-visits-migration-to-10000.md

Example of a database size limit for Places History in Firefox for Android.

```java
private static final long MAX_PLACES_DB_SIZE_BYTES = 75 * 1024 * 1024;
```

--------------------------------

### MozAdsClientBuilder Configuration

Source: https://github.com/mozilla/application-services/blob/main/components/ads-client/docs/usage-swift.md

Demonstrates how to use the MozAdsClientBuilder to configure and create an instance of the ads client. This includes setting the environment, cache configuration, and telemetry.

```APIDOC
## `MozAdsClientBuilder`

Builder for configuring and creating the ads client. Use the fluent builder pattern to set configuration options.

### Methods

- **`MozAdsClientBuilder()`** - Creates a new builder with default values
- **`environment(environment: MozAdsEnvironment)`** - Sets the MARS environment (Prod, Staging, or Test)
- **`cacheConfig(cacheConfig: MozAdsCacheConfig)`** - Sets the cache configuration
- **`telemetry(telemetry: MozAdsTelemetry)`** - Sets the telemetry implementation
- **`build()`** - Builds and returns the configured client

### Configuration Options

| Configuration  | Type                  | Description                                                                                            |
| -------------- | --------------------- | ------------------------------------------------------------------------------------------------------ |
| `environment`  | `MozAdsEnvironment`   | Selects which MARS environment to connect to. Unless in a dev build, this value can only ever be Prod. Defaults to Prod. |
| `cacheConfig`  | `MozAdsCacheConfig?`  | Optional configuration for the internal cache.                                                         |
| `telemetry`    | `MozAdsTelemetry?`    | Optional telemetry instance for recording metrics. If not provided, a no-op implementation is used.    |

### Configuration Example

```swift
let cache = MozAdsCacheConfig(
    dbPath: "/tmp/ads_cache.sqlite",
    defaultCacheTtlSeconds: 600,   // 10 min
    maxSizeMib: 20                 // 20 MiB
)

let telemetry = AdsClientTelemetry()

let client = MozAdsClientBuilder()
    .environment(environment: .prod)
    .cacheConfig(cacheConfig: cache)
    .telemetry(telemetry: telemetry)
    .build()
```
```

--------------------------------

### Rust Places History Insert Example

Source: https://github.com/mozilla/application-services/blob/main/components/places/README.md

Illustrates inserting a place into the history using the Rust implementation of the Places API.

```rust
let visits = vec![Visit { date, transition: ...} ];
let place = Place { url, title: ..., visits };
places::api::history::insert(db, place);
```

--------------------------------

### Build xcframework for Focus iOS

Source: https://github.com/mozilla/application-services/blob/main/docs/howtos/locally-published-components-in-focus-ios.md

Navigate to the ios-rust directory in your local application-services checkout and run this script to build the xcframework for Focus.

```bash
$ ./build-xcframework.sh --focus
```

--------------------------------

### JavaScript Places History Insert Example

Source: https://github.com/mozilla/application-services/blob/main/components/places/README.md

Demonstrates how to insert a new place into the history using the JavaScript Places API.

```javascript
let visits = [{date: ..., transitition: ...}];
let place = {url: "http...", title: ..., visits};
PlacesUtils.history.insert(place);
```

--------------------------------

### Build Full XCFramework

Source: https://github.com/mozilla/application-services/blob/main/megazords/ios-rust/README.md

Run this script to produce a zip file containing the compiled Rust code, C headers, and Swift module maps for all target iOS platforms.

```bash
#!/bin/bash
$> ./build-xcframework.sh
```

--------------------------------

### Create Python Symlink on macOS

Source: https://github.com/mozilla/application-services/blob/main/docs/building.md

Creates a symlink for the 'python' command to point to the same Python 3 version installed by Homebrew. This ensures consistency.

```shell
PYPATH=$(which python3); ln -s $PYPATH `dirname $PYPATH`/python
```

--------------------------------

### Clear Old NSS Build Artifacts

Source: https://github.com/mozilla/application-services/blob/main/docs/howtos/upgrading-nss-guide.md

Before installing an updated NSS version, clear any old build artifacts and perform a clean cargo build.

```bash
rm -rf ./libs/desktop && cargo clean
```