What does this PR do?

This PR introduces DatadogFlags (dd-sdk-android-flags), a new module for feature flag evaluation in Android applications. The module enables dynamic configuration and A/B testing by integrating with Datadog's Feature Flag product.

Key capabilities:

• Feature flag evaluation with type-safe APIs for boolean, string, number (int/double), and JSON values
• Automatic exposure tracking and RUM integration for correlating flags with user sessions
• Local storage with persistent caching of flag assignments using DataStore
• Evaluation context management (user attributes, targeting keys)
• Named client support for multi-project or multi-environment scenarios
• Bounded LRU cache for exposure event de-duplication to prevent duplicate tracking

Motivation

This feature allows Android developers to dynamically control application behavior through feature flags, enabling:

• Safe feature rollouts with gradual releases
• A/B testing and experimentation
• Runtime configuration without app updates
• Correlation of feature usage with application performance and user behavior through RUM integration

This implementation follows similar patterns established in the Datadog iOS SDK and aligns with OpenFeature specification principles for provider API design.

Additional Notes

Module Architecture

Core Components:

• FlagsClient - Main API interface for flag evaluation with methods like resolve(), resolveBooleanValue(), resolveStringValue(), resolveIntValue(), resolveDoubleValue(), and resolveStructureValue()
• DatadogFlagsClient - Production implementation that integrates with Datadog's flag evaluation system, manages flag resolution, type conversion, and tracking
• FlagsRepository - Manages Flag and evaluation context storage and, retrieval using DataStore for persistent caching
• PrecomputedAssignmentsDownloader - Handles fetching precomputed flag assignments from CDN endpoints via HTTP requests
• PrecomputedAssignmentsRequestFactory - Factory for creating authenticated HTTP requests to the Datadog feature flags service
• PrecomputeMapper - Parses and maps JSON responses from the CDN into internal flag models
• EvaluationsManager - Orchestrates flag evaluation context updates and triggers background fetching of flag assignments
• ExposureEventsProcessor - Tracks flag evaluations with bounded LRU cache for de-duplication, preventing duplicate exposure events
• RumEvaluationLogger - Reports flag evaluations to RUM for correlation with user sessions and application behavior
• FlagsFeature - Core feature registration, lifecycle management, and client registry

Supporting Components:

• FlagsConfiguration - Configuration for RUM integration, exposure tracking, and custom endpoints
• EvaluationContext - Contains targeting key and attributes for flag evaluation
• ResolutionDetails - Comprehensive resolution information including value, variant, reason, error details, and metadata
• FlagValueConverter - Type-safe conversion between flag values and expected types with validation
• NoOpFlagsClient - Fallback client implementation for graceful error handling when feature is not properly initialized

Related PRs

• Feature flagging [WIP] - Initial work on feature flagging
• feat: context management - Implement context management for flag evaluation
• Send exposures as batches - Add exposure event batching
• fix and improve tests, context management - Improve tests and context handling
• Add a persistence layer - Implement DataStore-based persistence
• chore: Refactor FlagsProvider and FlagsClient into one - Consolidate provider and client
• Flags.enable and FlagsClient APIs - Core API implementation
• feat: custom flagging endpoint and assignment download refactoring - Add custom endpoint support and refactor assignment fetching
• feat: DatadogSite extension for Flags endpoint - Add site-specific endpoint support
• Generic resolve method - Implement generic resolve() method with ResolutionDetails
• FFL-1113: RUM Evaluation Tracking - Add RUM integration for flag evaluations
• FL-1115: Support custom endpoints for exposures - Add custom exposure endpoint configuration
• FFL-1236 Add CountDownLatch to FlagsRepository - Improve repository synchronization
• FFL-1237: Add telemetry for critical paths - Add telemetry logging for failures
• FFL-1145: Update documentation - Add comprehensive documentation
• FFL-1185 generate ExposureEvent from schema - Generate exposure event models from JSON schema
• feat: Graceful mode and error logging policies - Implement graceful error handling
• PROVIDER_NOT_READY state - Add provider state support

Key Features

1. Type-Safe Flag Resolution:

   • Convenience methods for common types (boolean, string, int, double, JSON)
   • Detailed resolve() method with comprehensive metadata and error information
   • Automatic type conversion with fallback to default values on mismatch

3. Exposure Tracking:*

   • Track when user is exposed to a flag treatment via EvP track
   • De-duplicated exposure event logging with bounded LRU cache
   • Configurable exposure tracking via FlagsConfiguration.trackExposures
   • JSON schema-based event serialization

4. RUM Integration:

   • Automatic attachment of flag evaluations to RUM views
   • Correlation with user sessions for analysis
   • Configurable via FlagsConfiguration.rumIntegrationEnabled

5. Named Client Support:

   • Multiple named clients per SDK instance for different domains
   • Thread-safe client registry within FlagsFeature
   • Retrieval of existing clients via FlagsClient.get(name)

6. Persistent Storage:

   • DataStore-based repository for caching flag assignments
   • Survives app restarts for consistent flag evaluation
   • Background fetching with asynchronous context updates

7. Error Handling:

   • Comprehensive error codes (FLAG_NOT_FOUND, TYPE_MISMATCH, PARSE_ERROR, etc.)
   • Graceful degradation with default values
   • NoOp client fallback for missing feature initialization

Configuration Options

val flagsConfig = FlagsConfiguration.Builder()
    .rumIntegrationEnabled(true)  // Enable RUM integration (default: true)
    .trackExposures(true)          // Enable exposure tracking (default: true)
    .useCustomFlagEndpoint(url)    // Custom CDN endpoint (optional)
    .useCustomExposureEndpoint(url) // Custom exposure endpoint (optional)
    .build()

Flags.enable(flagsConfig)

Usage Example

// Enable feature
Flags.enable(FlagsConfiguration.Builder().build())

// Create client
val client = FlagsClient.Builder().build()

// Set evaluation context
client.setEvaluationContext(
    EvaluationContext(
        targetingKey = "user-123",
        attributes = mapOf("plan" to "premium")
    )
)

// Evaluate flags
val enabled = client.resolveBooleanValue("new-feature", false)

// Get detailed resolution
val result = client.resolve("experiment-variant", "control")
println("Value: ${result.value}, Variant: ${result.variant}")

Review checklist (to be filled by reviewers)

• Feature or bugfix MUST have appropriate tests (unit, integration, e2e)
• Make sure you discussed the feature or bugfix with the maintaining team in an Issue
• Make sure each commit and the PR mention the Issue number (cf the CONTRIBUTING doc)