Android Documentation

Technical Documentation: duckduckgo/Android

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

DuckDuckGo Android

Welcome to our android application. We are excited to engage the community in development, see CONTRIBUTING.md.

We are hiring! Copy Chapter

DuckDuckGo is growing fast and we continue to expand our fully distributed team. We embrace diverse perspectives, and seek out passionate, self-motivated people, committed to our shared vision of raising the standard of trust online. If you are a senior software engineer capable in either iOS or Android, visit our careers page to find out more about our openings!

Building the Project Copy Chapter

We use git submodules and so when you are checking out the app, you'll need to ensure the submodules are initialized properly. You can use the --recursive flag when cloning the project to do this.

git clone --recursive https://github.com/duckduckgo/android.git

Alternatively, if you already have the project checked out, you can initialize the submodules manually.

git submodule update --init

Terminology Copy Chapter

We have taken steps to update our terminology and remove words with problematic racial connotations, most notably the change to main branches, allow lists, and blocklists. Closed issues or PRs may contain deprecated terminology that should not be used going forward.

Contribute Copy Chapter

Please refer to contributing.

Discuss Copy Chapter

Contact us at https://duckduckgo.com/feedback if you have feedback, questions or want to chat. You can also use the feedback form embedded within our Mobile App - to do so please navigate to Settings and select "Leave Feedback".

License Copy Chapter

DuckDuckGo android is distributed under the Apache 2.0 license.

.Claude Docs Android Design System (`.claude/docs/android-design-system.md`) Copy Section

Android Design System (ADS)

The design system lives in android-design-system/design-system/; View components are under
com.duckduckgo.common.ui.view.*. Use ADS components instead of raw Android/Material widgets.

This rule is the component index and the constraints. For a component's API, read its class — the
signatures are not repeated here.

What breaks the build Copy Chapter

Lint fails the build on all of these (lint-rules/src/main/java/com/duckduckgo/lint/ui/):

• Raw Button, TextView, SwitchView in XML
• style= on any ADS component; a custom style not prefixed Widget.DuckDuckGo.
• @color/ references in XML — use ?attr/daxColor* so both themes work
• A plain View used as a divider
• AlertDialog / MaterialAlertDialog; a raw BottomSheetDialog without the ADS style
• background_skeleton set as the background of a SkeletonView
• On DaxButton*: android:textStyle, android:textColor, android:textAppearance,
  android:textAllCaps, android:tint, and android:layout_height unless wrap_content
• On DaxTextView: android:textAppearance, android:textAllCaps, android:tint,
  android:textSize, android:textStyle, android:fontFamily

Components Copy Chapter

Pick by intent, never by style.

Buttons — `view.button.*` Copy Section

DaxButtonPrimary · DaxButtonSecondary · DaxButtonGhost · DaxButtonGhostAlt ·
DaxButtonDestructive · DaxButtonDestructiveSecondary · DaxButtonGhostDestructive

GhostAlt is a ghost button placed on an alternate (non-default) background. Of the destructive
variants, pick by emphasis: Destructive (filled) → DestructiveSecondary → GhostDestructive.

Accepted attributes: android:text, android:enabled, app:icon,
app:daxButtonSize="large|small" (default small — note the dax prefix).

Between stacked buttons use @dimen/keyline_1 (4dp), not 16dp: buttons carry 6dp insets top and
bottom, so 4+6+6 gives the intended 16dp of visual spacing.

Text — `view.text.DaxTextView` Copy Section

One component for all text. Pick app:typography by semantic role; never set size or weight.

title · h1 · h2 · h3 · h4 · h5 · body1 (default) · body1_bold · body1_mono ·
body2 · body2_bold · button · caption · caption_allCaps · onboarding_title ·
onboarding_body

app:textType: primary (default) · secondary

Text input — `view.text.DaxTextInput` Copy Section

app:type: single_line · multi_line · password · form_mode · ip_address · url.
app:editable toggles editability.

Set error for invalid user input only. Network and other external failures go in a Snackbar, not
the field.

List items — `view.listitem.*` Copy Section

All extend DaxListItem, which carries the shared primary/secondary text, leading/trailing icon,
and switch API. Pick by the content you have:

app:leadingIconImageBackground: none · circular · rounded.
Leading-icon sizes come from IconSize: Small, Medium, Large, ExtraLarge.

Dialogs — `view.dialog.*` Copy Section

Builders taking an EventListener for button callbacks: TextAlertDialogBuilder (standard alert),
StackedAlertDialogBuilder (three or more vertically stacked options), RadioListAlertDialogBuilder
(single selection).

Bottom sheets Copy Section

ActionBottomSheetDialog and PromoBottomSheetDialog cover the two standard patterns. A custom
BottomSheetDialog must be constructed with the ADS style
(com.duckduckgo.mobile.android.R.style.Widget_DuckDuckGo_FireDialog); a BottomSheetDialogFragment
inherits it from the theme.

Other components Copy Section

Colors Copy Chapter

Theme attributes, never @color/:

?attr/daxColorBackground (screen) · ?attr/daxColorSurface (toolbars, navigation, dialogs) ·
?attr/daxColorContainer (object containers, e.g. favicon background) · ?attr/daxColorPrimaryText ·
?attr/daxColorSecondaryText · ?attr/daxColorTertiaryText (hints, placeholders) ·
?attr/daxColorPrimaryIcon · ?attr/daxColorSecondaryIcon · ?attr/daxColorAccentBlue (accent,
CTAs) · ?attr/daxColorDestructive · ?attr/daxColorLines (dividers)

In Kotlin: context.getColorFromAttr(R.attr.daxColorPrimaryText).
In a vector drawable that must follow the theme: android:fillColor="?attr/daxColorPrimaryIcon".

Adding an icon the project doesn't have yet: read .claude/docs/icons.md — it must be fetched from the
internal Icons repository, never invented.

Spacing Copy Chapter

Use keylines rather than arbitrary dp. The values are here so a dp figure from a design spec can be
mapped back to the right resource:

Defined in design-system-dimensions.xml.

.Claude Docs Architecture (`.claude/docs/architecture.md`) Copy Section

Android Architecture

Core Principle: Decoupling Over Everything Copy Chapter

Features communicate through -api modules only. An -impl module must never depend on another -impl module. If two features need to interact, one exposes an interface in its -api, the other injects it. This is non-negotiable — it prevents circular dependencies and keeps the Dagger graph clean.

Module Structure Copy Chapter

Every feature follows the -api / -impl split:

my-feature/
  my-feature-api/       ← interfaces, data classes, no implementation
  my-feature-impl/      ← implementation, UI, DI bindings

• my-feature-impl depends on my-feature-api
• my-feature-impl depends on other features' -api modules only — never their -impl
• settings.gradle auto-discovers modules 2 levels deep — no manual include needed
• New -impl modules must be added to app/build.gradle to enter the Dagger graph
• UI resources (layouts, drawables, strings) live inside the -impl module, not a separate UI module
• String resource files are named by feature: strings-my-feature.xml (not strings.xml)

Compile-time dependency rules Copy Section

Enforced in the root build.gradle. Violations fail the build.

Conventions enforced by lint Copy Section

The lint-rules module fails the build on these (UI/design-system rules are covered separately):

• Hardcoded coroutine dispatchers — inject them instead
• @Singleton — use @SingleInstanceIn
• Extending Fragment directly — use DuckDuckGoFragment
• lifecycleScope inside a Fragment — use viewLifecycleOwner.lifecycleScope
• Registering lifecycle observers directly — drive state from a ViewModel
• retrofit.create() — get the service from DI
• NonCancellable when launching a coroutine
• postValue() on a SingleLiveEvent
• Underscores in a RemoteFeature name
• Raw WebViewCompat APIs — use WebViewCompatWrapper; post messages via PostMessageWrapperPlugin
• RobolectricTestRunner in @RunWith

Dependency Injection (Anvil / Dagger) Copy Chapter

Scopes Copy Section

Use @SingleInstanceIn(AppScope::class) — not @Singleton (javax). @Singleton conflicts with AppComponent's scope.

Common annotations Copy Section

// Singleton binding
@SingleInstanceIn(AppScope::class)
@ContributesBinding(AppScope::class)
class RealFoo @Inject constructor(...) : Foo

// Override an existing binding (higher rank wins)
@ContributesBinding(AppScope::class, rank = 1)

// ViewModel
@ContributesViewModel(FragmentScope::class)
class FooViewModel @Inject constructor(...) : ViewModel()

// Plugin contribution (multibinding)
@ContributesMultibinding(AppScope::class)
class MyPlugin @Inject constructor(...) : SomePlugin

// Remote feature flag
@ContributesRemoteFeature(scope = AppScope::class, featureName = "myFeature")
interface MyFeature : Feature {
    @Toggle.DefaultValue(DefaultFeatureValue.INTERNAL)
    fun myToggle(): Toggle
}

DefaultFeatureValue.INTERNAL = enabled only in internal/debug builds.

What each scope can reach Copy Section

• A Fragment or View (FragmentScope, ViewScope) parents to ActivityComponent, so it can access
  ActivityScope bindings such as @ActivityContext Context.
• A Receiver or Service (ReceiverScope, ServiceScope) parents directly to AppComponent, so it can
  only access AppScope bindings — there is no @ActivityContext available.
• VpnScope also parents to AppComponent and is only for the VPN secondary process.

For the component diagram and for diagnosing "could not find dagger component" crashes, read
.claude/docs/dagger-scopes.md.

Activity Context Copy Section

@ActivityContext Context and AppCompatActivity are provided at ActivityScope via DaggerActivityScopedModule. Inject them with:

@ContributesBinding(ActivityScope::class)
class RealFoo @Inject constructor(
    @ActivityContext private val context: Context,
) : Foo

Never pass Context as a parameter through an interface if DI can provide it at the right scope.

App Coroutine Scope Copy Section

@AppCoroutineScope private val appScope: CoroutineScope

UI Patterns Copy Chapter

Activity and Fragment base classes Copy Section

Activities extend DuckDuckGoActivity, fragments extend DuckDuckGoFragment (lint enforces the
latter). These are not optional conveniences: they are the DaggerActivity/DaggerFragment
subclasses carrying
@HasMemberInjections, so a screen that extends AppCompatActivity or Fragment directly gets no
member injection and no viewModelFactory. DuckDuckGoActivity additionally applies the stored
theme, listens for theme changes, and handles edge-to-edge setup.

Override applyFireTheme to true only on activities whose look should follow the fire-mode theme;
those must inject BrowserMode to compute it.

ViewModels Copy Section

Commands are emitted via a Channel<Command>:

private val _commands = Channel<Command>(Channel.BUFFERED)
val commands: Flow<Command> = _commands.receiveAsFlow()

State is StateFlow derived via combine + stateIn.

Coroutine Jobs Copy Section

Prefer ConflatedJob over a raw Job variable or a Map<Key, Job> when you need to cancel-and-replace a running job:

private var dwellJob by ConflatedJob()
dwellJob = scope.launch { /* cancels previous */ }

In a Fragment, collect on viewLifecycleOwner.lifecycleScope, never the Fragment's own
lifecycleScope — the latter outlives the view and leaks collectors across view recreation.

Navigation Copy Chapter

Navigate between activities with GlobalActivityStarter (from navigation-api). Never construct or
start an Intent directly — the starter keeps navigation decoupled across modules.

Do not use startIntent() + launcher.launch(intent) — use startForResult() instead.
startIntent() returns a nullable Intent and launch(null) crashes.

Registering a screen, the overloads and deeplink support: .claude/docs/navigation.md.

Deciding whether typed input is a URL or a search query: .claude/docs/url-classification.md
(UriString.isWebUrl() is not the answer).

Logging Copy Chapter

import logcat.logcat   // correct
// NOT: import com.squareup.logcat.logcat

Testing Copy Chapter

• JUnit4 (@Test, not JUnit5/Jupiter)
• Assertions: org.junit.Assert.*
• Mocking: org.mockito.kotlin.mock() + whenever()
• Coroutines: CoroutineTestRule + runTest { }
• Test files mirror the class: RealFoo.kt → RealFooTest.kt
• No coroutine test setup needed for pure logic classes
• RobolectricTestRunner is banned in @RunWith (lint)

UI tests are Maestro flows under .maestro/, grouped by feature area; the conventions for writing and
running them are in .claude/rules/maestro-ui-tests.md.

.Claude Docs Contributions (`.claude/docs/contributions.md`) Copy Section

Contributions

Branch Naming Copy Chapter

<purpose>/<git-username>/<feature-name>

• purpose: feature, fix, refactor, chore, poc, etc.
• name: the author's name or alias
• feature-name: kebab-case description

Examples: feature/jsmith/duck-ai-url-routing, fix/jsmith/bookmark-crash

Commit Messages Copy Chapter

Use the imperative mood in the subject line (e.g. "Add feature X", not "Added feature X"). Keep the subject under 72 characters. Add a blank line before the body if more context is needed. Reference the Asana task URL in the body.

PR body Copy Chapter

Read @.github/PULL_REQUEST_TEMPLATE.md and use it as the PR body exactly — do not skip or reorder sections, do not add content above the first line of the template.

Fill in the template sections as follows:

• Task/Issue URL: the Asana task URL
• Description: summarise what was changed and why
• Steps to test: reviewer-facing steps per scenario; specific enough that someone unfamiliar with the code can follow them
• UI changes: before/after screenshots or recordings; write No UI changes in both columns for pure logic/backend changes

Tech Design Copy Chapter

Larger or cross-cutting changes — work that spans multiple modules or APIs, introduces a new integration, or otherwise can't be captured by a single self-contained API proposal — should also be backed by a tech design document. The tech design covers the overall approach; the API proposals cover each public surface it introduces. A big feature often has one tech design and several API proposals.

Surface this early. When you first scope a change, judge whether it's cross-cutting like this. If it is, tell the user up front that a tech design will be needed, so it can be written and reviewed before implementation — don't wait until PR time to raise it.

Before opening a PR for a change of this size, ask the user for the tech design link and add it to the Tech Design URL field of the PR body — do not open the PR unless the tech design exists and is linked, or the user explicitly confirms that no tech design is needed. Small, self-contained changes don't need one; leave the field blank.

API Proposals Copy Chapter

Any change to a public API — a .kt/.java file under a *-api module's src/main — must be accompanied by an approved API Proposal. -api modules are the contract other modules depend on, so the team reviews the public surface before it ships.

Surface this early. When you first scope a change, check whether it will touch a -api public surface. If it will, tell the user up front that an approved API Proposal is required, so it can be started before implementation — don't wait until PR time to raise it.

Before opening a PR, check whether the changes touch a public API (any .kt/.java file under a *-api module's src/main). If they do, stop and explicitly ask the user for the API Proposal link(s) — do not open the PR until they provide them. The proposal should exist and be linked before the PR goes up. If the user confirms the change does not alter the public surface (e.g. KDoc, comments, tests, dependency bumps), record None instead.

An API Proposal is an Asana task in the Android Proposals project.

In the PR: list the proposal link(s) in the API Proposals field of the PR body — one per line; a single PR may carry more than one. Use None for the no-public-API-change case described above.

Creating PRs Copy Chapter

This repository uses GitHub stacked PRs (gh stack) for stacked work.

• gh stack init to start a stack on top of develop (or gh stack init ... to stack existing branches)
• gh stack add to add a new branch on top of the current stack
• gh stack submit to push all branches and create or update their PRs — pass --auto in non-interactive environments
• gh stack sync / gh stack rebase to keep the stack up to date with the remote and develop

For a single PR that isn't part of a stack, push the branch and open the PR with gh api repos/duckduckgo/Android/pulls --method POST — do not use gh pr create, which fails with a Projects Classic deprecation warning.

.Claude Docs Dagger Scopes (`.claude/docs/dagger-scopes.md`) Copy Section

Dagger scope hierarchy and injection crashes

The hierarchy determines what dependencies each scope can access, where its factory lookup happens,
and which HasDaggerInjector performs the injection. It is encoded implicitly in the Anvil-generated
_SubComponent files — this diagram is the source of truth:

DuckDuckGoApplication [HasDaggerInjector]
└── AppComponent [AppScope]
    │   Factory map contains: ActivityComponent.Factory, ReceiverSubComponent factories,
    │                         ServiceSubComponent factories, VpnScope factories
    │
    ├── ActivityComponent [ActivityScope]  ← subcomponent of AppComponent
    │   │   Factory map contains: FragmentSubComponent factories, ViewSubComponent factories
    │   │   Provided bindings: @ActivityContext Context, AppCompatActivity
    │   │
    │   ├── EachFragment_SubComponent [FragmentScope]  ← subcomponent of ActivityComponent
    │   └── EachView_SubComponent [ViewScope]          ← subcomponent of ActivityComponent
    │
    ├── EachReceiver_SubComponent [ReceiverScope]  ← subcomponent of AppComponent
    └── EachService_SubComponent [ServiceScope]    ← subcomponent of AppComponent

FragmentScope and ViewScope factories are looked up through DaggerActivity.injectorFactoryMap.
ReceiverScope, ServiceScope and VpnScope factories are looked up through
DuckDuckGoApplication.injectorFactoryMap.

The parent scope follows from the scope passed to @InjectWith; Anvil generates the ParentComponent
and its @ContributesTo. You never set it manually.

Debugging "could not find dagger component" Copy Chapter

• Crash in a Fragment/View injection → check DaggerActivity.injectorFactoryMap; the class is missing
  @InjectWith(FragmentScope::class) or @InjectWith(ViewScope::class).
• Crash in a Receiver/Service injection → check DuckDuckGoApplication.injectorFactoryMap; the class
  is missing @InjectWith(ReceiverScope::class) or @InjectWith(ServiceScope::class).

Member injection into a transitively-typed field Copy Chapter

Anvil reporting Couldn't resolve ClassReference … File is unknown for an @Inject field means the
field's type is only available transitively. Add the module that declares it as a direct dependency.

.Claude Docs Icons (`.claude/docs/icons.md`) Copy Section

Adding an icon

Ask the user for the icon name, then fetch it from the internal DDG Icons repository at
https://dub.duckduckgo.com/duckduckgo/Icons. Do not guess icon names and do not skip this step —
inventing a name produces an asset that doesn't match the design system.

• Keep the SVG file name as close to the original as possible, and import it as a vector asset
• An icon used by a single feature belongs in that feature's -impl module, not common-ui
• For an icon that must follow the theme, set android:fillColor="?attr/daxColorPrimaryIcon"

.Claude Docs Lateinit Hazards (`.claude/docs/lateinit-hazards.md`) Copy Section

`lateinit var` initialization hazards

Reading a lateinit var before it has been assigned throws UninitializedPropertyAccessException at runtime. There is no compile-time check — only review and runtime crashes catch it. When writing or reviewing code that declares or reads a lateinit var, walk through these cases.

View subclasses with `@Inject lateinit var` Copy Chapter

A View annotated with @InjectWith(ViewScope::class) injects its @Inject lateinit var members inside onAttachedToWindow(), via AndroidSupportInjection.inject(this). The fields are uninitialized between construction and attach.

The trap: a parent or manager class can call a public/internal/override method on the view immediately after addView(…) — before the view tree is attached. If that method reads an @Inject lateinit var directly, it crashes.

When reviewing a View subclass, treat every public / internal / override method that reads an @Inject lateinit var as suspect. It is safe only if at least one is true:

• the read happens in onAttachedToWindow() (after inject(this)) or onDetachedFromWindow()
• the read is inside doOnAttach { … } (from androidx.core.view)
• the read is inside a lambda that only fires post-attach (click listener, flow collector that is launchIn(…) started inside onAttachedToWindow, post { … }, etc.)
• the read is guarded by ::propertyName.isInitialized
• the method is private and every call site is one of the above (verify by checking each caller — do not assume)

When in doubt, the standard fix is to wrap the body in doOnAttach { … }. It runs immediately if the view is already attached, and defers otherwise — same behaviour as before in the common case, no crash in the edge case.

Real-world bugs caused by missing this:

• PR #8424 — NativeInputModeWidget.configure() / configureContextual() / setWidgetPosition() read viewModel (a @Inject lateinit var) directly; RealNativeInputManager.attachWidget() called them right after addView(), before attach. Fix: wrap each body in doOnAttach { … }.
• PR #8461 — DuckDuckGoWebView.setContentAllowsSwipeToRefresh() read browserUiLockFeature unconditionally. Fix: if (!allowed || (::browserUiLockFeature.isInitialized && browserUiLockFeature.self().isEnabled())).
• PR #8577 — NativeInputModeWidget.applyDefaultTogglePosition() read injected state directly. Fix: wrap in doOnAttach { … }.

Construction-time reads in any class Copy Chapter

Independent of class type — even a plain Kotlin class with no DI involvement — a lateinit var is also uninitialized during the primary constructor's run, which includes:

• property initializers (val x = lateinitProp.foo())
• init { … } blocks
• secondary constructor bodies that delegate to the primary

If a property initializer or init block reads a lateinit var before any earlier init block or initializer has assigned it, that read crashes. The order is source declaration order, not visual placement of the lateinit var declaration.

class Foo {
    lateinit var bar: String
    val length: Int = bar.length          // ❌ crash — bar not assigned yet
    init { bar = "x" }                    // assignment runs after the val above
}

class Foo {
    lateinit var bar: String
    init { bar = "x" }                    // assigns first
    val length: Int = bar.length          // ✓ safe — bar already assigned
}

For Fragments, Activities, Services, ViewModels and other framework-managed classes, the construction-time hazard still applies even though their regular method bodies are safe (those run post-injection in onAttach / onCreate). Concretely:

• Fragment/Activity: an init { … } or property initializer reading an @Inject lateinit var crashes — injection has not run yet. By the time onCreate / onAttach runs, the read is safe.
• ViewModel with @Inject constructor(…): prefer constructor-injected val for required deps. lateinit var on a ViewModel is a smell — if you see it, ask why it isn't a constructor parameter.

The universal escape hatch — if (::propertyName.isInitialized) { … } — works for any class type. Reach for it only when the access really is optional. If the property is required, fix the initialization order instead, don't paper over it with the guard.

.Claude Docs Navigation (`.claude/docs/navigation.md`) Copy Section

Navigating between screens

Navigation goes through GlobalActivityStarter (from navigation-api) so screens stay decoupled
across modules.

Registering a screen Copy Chapter

Define an ActivityParams type and annotate the activity. Anvil codegen generates the mapper.

// In the feature's -api module
data class MyScreenParams(val id: String) : GlobalActivityStarter.ActivityParams

// In the feature's -impl module
@ContributeToActivityStarter(MyScreenParams::class)
class MyActivity : DuckDuckGoActivity() {
    private val params by lazy { intent.getActivityParams(MyScreenParams::class.java) }
}

Use screenName to opt into deeplink support:

@ContributeToActivityStarter(MyScreenParams::class, screenName = "myScreen")

Choosing the overload Copy Chapter

For ActivityParams:

Each takes an optional trailing options: Bundle?, and each has a DeeplinkActivityParams
counterpart for deeplink entry points.

FLAG_ACTIVITY_NEW_TASK is added automatically when context is not an Activity (Services,
broadcast receivers, JS message handlers, etc.) — do not add it manually.

.Claude Docs Pixels (`.claude/docs/pixels.md`) Copy Section

Pixels

Pixels are lightweight telemetry events sent via HTTP with a name and optional parameters. They are used for:

• Feature usage events (e.g., button clicks, screen impressions, toggle changes)
• Error monitoring (e.g., network failures, parsing errors, crash reports)
• Conversion and retention (e.g., subscription purchase, activation, onboarding completion)

The privacy invariants every pixel must satisfy (no PII, no URLs, no correlation IDs, bucketed numbers,
bounded enums) are in CLAUDE.md and apply to all outbound data — they are not repeated here.

Types of Pixels Copy Chapter

Standard Pixels Copy Section

Sent every time the event occurs. Use for events where per-occurrence volume matters.

Daily Pixels Copy Section

Sent at most once per calendar day per event. Use to measure the number of unique users affected by something (e.g., how many users hit a particular error per day). Most daily pixel implementations also support a "count" variant that fires every time.

When a pixel fires as a plain count+daily pair with identical parameters, register it as one
definition entry using the first_daily_count suffix rather than two separate _count/_daily
entries — see .claude/rules/pixel-definitions.md. The firing code is unchanged either way: it still
calls pixel.fire() twice with the explicit _count/_daily wire-string names.

Unique Pixels Copy Section

Sent once per install for the lifetime of the install. Use for one-time lifecycle events (e.g., first activation, first use of a feature).

Pixel Naming Copy Chapter

• Use underscores or hyphens as word separators. Be consistent within a feature area.
• Use clear, descriptive names. Anyone reading the pixel name should understand what it represents without additional context. Avoid cryptic abbreviations.
• Group related pixels with a common prefix (e.g., burn_started, burn_completed, burn_error).
• Embed dynamic data in parameters, not pixel names. Pixel names should be static string literals. Use query parameters for variable data.

# Good — static name with parameter
pixel: "burn_error", parameters: { "operation": "delete", "exceptionType": "IOException" }

# Bad — dynamic data in pixel name
pixel: "burn_error_delete_IOException"

Pixel Parameters Copy Chapter

• Prefer shared dictionary entries. If a parameter is used by multiple pixels, define it in params_dictionary and reference it by key.
• Use structured, typed parameters. Each parameter should have a clear type (string, integer, number, boolean) and, where possible, a bounded enum of allowed values.
• Include error context for error pixels. When a pixel reports an error, include enough information to diagnose the issue — error type, error code, failing step — without leaking PII.
• Bucket all numeric values. Durations, counts, sizes, and other continuous values must be bucketed into ranges.

# Good — bucketed duration
"duration_bucket": "1_to_5_min"

# Bad — exact value
"duration_ms": "237841"

Pixel Definition Files Copy Chapter

Every pixel fired in code must have a corresponding entry in a definition file under PixelDefinitions/pixels/definitions/. Without this, the pixel validation CI check will fail.

• Find the appropriate definition file for your feature area (or create a new one)
• Add an entry keyed by the full pixel name
• Include description, owners, triggers, parameters, and suffixes fields
• Choose triggers with the decision procedure in .claude/rules/pixel-definitions.md — classify by
  the event that causes the pixel to fire, and never default to ["other"]
• The owners field must contain the author's GitHub username
• Match the format of existing entries in the same file

For the definition-file schema, the dictionaries, and the local validation commands, read
.claude/rules/pixel-definitions.md.

Privacy Review & Triage Copy Chapter

Any PR that adds a new pixel or modifies the pixel registry (anything under PixelDefinitions/pixels — pixel definitions, wide-event definitions, and the shared params/suffixes dictionaries) must go through privacy triage. The mechanism is a single label:

• Apply the privacy review required label to the PR. This automatically creates a Privacy Triage task in Asana and adds the PR author as a collaborator; the Privacy Triage DRI follows up there. Applying the label is how the triage is created — there is no separate manual step.
• When an agent creates or helps create a pixel PR, it MUST add this label when opening the PR — apply it after creating the PR with gh pr edit <number> --add-label "privacy review required" (see .claude/docs/contributions.md for how the PR itself is opened; gh pr create is not used in this repo). If the agent cannot set labels, it must say so explicitly so the author applies it. This is in addition to updating the pixel definitions — both are required, do not skip either.
• Self-service still applies: you may proceed with implementation without blocking on triage where appropriate, but the label must still be applied so triage happens.

Modifying an existing pixel that isn't in the registry yet: first document the old pixel in the registry. If the change is small, note in the PR/code which parts are new; if it's large, split into two commits/PRs (one documenting the already-approved existing pixel, one for the change). If a prior triage is known, record it in the pixel's privacyReview property.

Full process: Pixels Triage using the Pixel Registry.

When to Use a Wide Event Instead Copy Chapter

Use a wide event rather than a pixel when:

• A user journey has multiple steps that can succeed or fail independently
• You need to understand where users drop off or encounter errors in a multi-step process
• The outcome of earlier steps affects the interpretation of later steps

Use both when a wide event makes sense but the journey spans a long time period where waiting for completion would delay monitoring.

For designing and implementing wide events, read .claude/rules/wide-events.md.

.Claude Docs Plugin System (`.claude/docs/plugin-system.md`) Copy Section

Plugin System

Two kinds of plugin points exist. Pick based on whether you need remote feature flag control.

`@ContributesPluginPoint` — basic Copy Chapter

PluginPoint<T> — Dagger multibinding under the hood. Returns all registered plugins, no runtime filtering.

// Declare (in -api or -impl module)
@ContributesPluginPoint(AppScope::class)
interface MyPlugin { fun doThing() }

// Contribute
@ContributesMultibinding(AppScope::class)
class MyPluginImpl @Inject constructor() : MyPlugin

// Contribute with explicit ordering (lower value = higher priority)
@ContributesMultibinding(AppScope::class)
@PriorityKey(100)
class MyPluginImpl @Inject constructor() : MyPlugin

// Consume
class Foo @Inject constructor(private val plugins: PluginPoint<MyPlugin>)
// plugins.getPlugins() → all plugins, in priority order if @PriorityKey is used

`@ContributesActivePluginPoint` — with remote feature flags + codegen Copy Chapter

ActivePluginPoint<T> — wraps a regular plugin point with two levels of feature-flag gating. The annotation processor generates all the boilerplate: a remote feature for the plugin point itself, a remote feature per plugin, a MultiProcessStore, and a wrapper that applies both guards at runtime.

Plugin point must be declared on a private interface (the codegen is the only consumer):

// The plugin interface must extend ActivePlugin
interface MyPlugin : ActivePlugin { fun doThing() }

// Declared with a private trigger interface (in -impl)
@ContributesActivePluginPoint(
    scope = AppScope::class,
    boundType = MyPlugin::class,
    featureName = "pluginPointMyPlugin",  // required, must start with "pluginPoint"
)
private interface MyPluginPointTrigger

Contribute a plugin:

@ContributesActivePlugin(
    scope = AppScope::class,
    boundType = MyPlugin::class,
    featureName = "pluginMyPluginImpl",            // required, must start with "plugin" (not "pluginPoint")
    parentFeatureName = "pluginPointMyPlugin",     // required, must match an existing plugin point's featureName
)
class MyPluginImpl @Inject constructor() : MyPlugin {
    // isActive() is generated — backed by its own remote feature flag
}

Consume:

class Foo @Inject constructor(private val plugins: ActivePluginPoint<MyPlugin>)
// plugins.getPlugins() → only plugins whose feature flag is enabled AND isActive() == true

How the gating works at runtime:

1. If the plugin point's own self() toggle is OFF → emptyList() immediately
2. Otherwise, filter each plugin by its individual pluginXxx() toggle (via isActive())

Naming conventions (enforced at compile time):

• featureName and parentFeatureName are required — blank or missing values fail the build.
• parentFeatureName must match an existing @ContributesActivePluginPoint's featureName. This is validated at compile time across modules (including sibling modules that don't depend on each other) via a sentinel/deferred-marker mechanism. A typo in parentFeatureName will fail the build.

All flags default to TRUE so newly contributed plugins are on by default and can be killed remotely.

.Claude Docs Translations (`.claude/docs/translations.md`) Copy Section

Translations

The app ships in 24 languages. Translation is automated: a Smartling repository connector reads
English strings from branches, and commits the translated files back to the same branch.

smartling-config.json (repo root) is the source of truth for the locale list and the file mapping:
every **/values/strings*.xml is sent for translation and comes back as
values-<locale>/strings*.xml.

Where strings go Copy Chapter

Translatable string files must be named strings-<module>.xml (app uses strings.xml), and must
carry both Smartling directives above the <resources> element — the MissingSmartlingRequiredDirectives
lint rule fails the build otherwise:

During development, add new strings to donottranslate.xml. Move them into the real strings file
only when the copy is final and you're ready to request translations: pushing half-finished copy costs
days, since each round trip through Smartling takes a few.

Rules for translatable strings Copy Chapter

1. Add an instruction only where the string isn't self-evident — always for a string with a
   placeholder, and for copy whose meaning depends on the screen around it. Translators see the
   instruction attribute and nothing else, not the surrounding code and not the screen. Plain
   unambiguous copy ("Settings", "Done") needs none; don't add one for its own sake.

   xml Copy

   <string name="authenticationDialogMessage" instruction="Placeholder is the name of a website">%1$s requires a username and password.</string>

2. Reuse copy that is already translated instead of adding a key for it. Common words like "Cancel"
   or "Done" live in the design system's strings-common-ui.xml and are translated in all 24 locales,
   so point at the existing string. A duplicate key means paying for a translation we already have.

3. Use positional placeholders — %1$s, %2$s, never bare %s. Word order differs by language, so
   translators need to be able to reorder them.

4. Don't skip plurals. Use `` where the English has a count; quantity sets differ per language.

5. Entity escaping is off globally. A string that needs escaping has to flip the directive around
   itself, and flip it back afterwards:

   xml Copy

   <string name="example">My escaped string here</string>

6. Constrained UI takes a character limit, declared above the string:

   xml Copy

7. Never put lint annotations inside a translated string — the next translation job overwrites the
   file and deletes them. Fix the underlying issue, or record the check in the lint baseline instead.

Prefer whole sentences with placeholders over sentence fragments concatenated in code: languages
reorder and inflect, and a fragment gives the translator nothing to work with.

Changing strings that are already translated Copy Chapter

Reusing a key with different copy leaves every locale holding a stale translation of the old text,
which is why an English change is delete-plus-new-key rather than an edit in place.

Fixing a translation is the one job that happens outside the repo — it needs a Smartling login, so an
agent cannot do it and should hand it to the developer.

Reference Copy Chapter

This file is the working reference — enough to add a string or request a translation without opening
anything else. The Asana sources are the authority behind it; read one only when this file is silent or
looks wrong, not up front:

• Android Smartling Translation Guide — the connector, branch naming, the Smartling rules
• Typical Development Flow and FAQs — an add/change/remove case this file doesn't cover
• Tips for better translation tokens — writing copy translators can work with
• How to Use Smartling for Translations — Smartling account setup, for a developer who needs dashboard access

When translations stall or a translation looks wrong, ask the
Translation/Localization AOR — people to
talk to, not a document to read.

.Claude Docs Url Classification (`.claude/docs/url-classification.md`) Copy Section

Deciding whether a string is a URL or a search query

Use QueryUrlPredictor (from browser-api). Do not use UriString.isWebUrl() for the decision —
its regex is too permissive, e.g. bbc.comcomcomcom passes.

private fun isNavigate(query: String): Boolean =
    if (queryUrlPredictor.isReady()) {
        queryUrlPredictor.classify(query) is Decision.Navigate
    } else {
        UriString.isWebUrl(query)  // fallback while native lib initialises
    }

• Decision is a sealed interface with Navigate(url) and Search(query) — both data classes.
• isReady() is false briefly at startup while the native library loads; always guard with a
  UriString.isWebUrl fallback.
• QueryUrlPredictor lives in browser-api and is injectable at AppScope. Decision is exported
  transitively via browser-api's api dependency on url-predictor-android.

--- METRICS ---

• Files Extracted: 12
• Estimated Token Budget: ~11200 tokens
• Canonical Reference: https://codewiki.google/github.com/duckduckgo/Android