feat: Support device_id as bucketing identifier for local evaluation

Add support for `bucketing_identifier` field on feature flags to allow
using `device_id` instead of `distinct_id` for hashing/bucketing in
local evaluation.

- When `bucketing_identifier: "device_id"`, use device_id for hash
  calculations instead of distinct_id
- device_id can be passed as method parameter or resolved from context
  via `get_context_device_id()`
- If device_id is required but not provided, raises InconclusiveMatchError
  to trigger server fallback
- Group flags ignore bucketing_identifier and always use group identifier

Author: andehen

posthog/client.py

@@ -1418,6 +1418,7 @@ def _compute_flag_locally(
         person_properties=None,
         group_properties=None,
         warn_on_unknown_groups=True,
+        device_id=None,
     ) -> FlagValue:
         groups = groups or {}
         person_properties = person_properties or {}
@@ -1459,12 +1460,14 @@ def _compute_flag_locally(
                 return False
 
             focused_group_properties = group_properties[group_name]
+            # Group flags use group identifier for hashing, ignore bucketing_identifier
             return match_feature_flag_properties(
                 feature_flag,
                 groups[group_name],
                 focused_group_properties,
                 self.feature_flags_by_key,
                 evaluation_cache,
+                skip_bucketing_identifier=True,
             )
         else:
             return match_feature_flag_properties(
@@ -1474,6 +1477,7 @@ def _compute_flag_locally(
                 self.cohorts,
                 self.feature_flags_by_key,
                 evaluation_cache,
+                device_id=device_id,
             )
 
     def feature_enabled(
@@ -1580,8 +1584,12 @@ def _get_feature_flag_result(
         evaluated_at = None
         feature_flag_error: Optional[str] = None
 
+        # Resolve device_id from context if not provided
+        if device_id is None:
+            device_id = get_context_device_id()
+
         flag_value = self._locally_evaluate_flag(
-            key, distinct_id, groups, person_properties, group_properties
+            key, distinct_id, groups, person_properties, group_properties, device_id
         )
         flag_was_locally_evaluated = flag_value is not None
 
@@ -1785,6 +1793,7 @@ def _locally_evaluate_flag(
         groups: dict[str, str],
         person_properties: dict[str, str],
         group_properties: dict[str, str],
+        device_id: Optional[str] = None,
     ) -> Optional[FlagValue]:
         if self.feature_flags is None and self.personal_api_key:
             self.load_feature_flags()
@@ -1804,6 +1813,7 @@ def _locally_evaluate_flag(
                         groups=groups,
                         person_properties=person_properties,
                         group_properties=group_properties,
+                        device_id=device_id,
                     )
                     self.log.debug(
                         f"Successfully computed flag locally: {key} -> {response}"
@@ -2106,12 +2116,17 @@ def get_all_flags_and_payloads(
             )
         )
 
+        # Resolve device_id from context if not provided
+        if device_id is None:
+            device_id = get_context_device_id()
+
         response, fallback_to_flags = self._get_all_flags_and_payloads_locally(
             distinct_id,
             groups=groups,
             person_properties=person_properties,
             group_properties=group_properties,
             flag_keys_to_evaluate=flag_keys_to_evaluate,
+            device_id=device_id,
         )
 
         if fallback_to_flags and not only_evaluate_locally:
@@ -2142,6 +2157,7 @@ def _get_all_flags_and_payloads_locally(
         group_properties=None,
         warn_on_unknown_groups=False,
         flag_keys_to_evaluate: Optional[list[str]] = None,
+        device_id: Optional[str] = None,
     ) -> tuple[FlagsAndPayloads, bool]:
         person_properties = person_properties or {}
         group_properties = group_properties or {}
@@ -2171,6 +2187,7 @@ def _get_all_flags_and_payloads_locally(
                         person_properties=person_properties,
                         group_properties=group_properties,
                         warn_on_unknown_groups=warn_on_unknown_groups,
+                        device_id=device_id,
                     )
                     matched_payload = self._compute_payload_locally(
                         flag["key"], flags[flag["key"]]

posthog/feature_flags.py

@@ -44,8 +44,8 @@ def _hash(key: str, distinct_id: str, salt: str = "") -> float:
     return hash_val / __LONG_SCALE__
 
 
-def get_matching_variant(flag, distinct_id):
-    hash_value = _hash(flag["key"], distinct_id, salt="variant")
+def get_matching_variant(flag, hashing_identifier):
+    hash_value = _hash(flag["key"], hashing_identifier, salt="variant")
     for variant in variant_lookup_table(flag):
         if hash_value >= variant["value_min"] and hash_value < variant["value_max"]:
             return variant["key"]
@@ -68,7 +68,13 @@ def variant_lookup_table(feature_flag):
 
 
 def evaluate_flag_dependency(
-    property, flags_by_key, evaluation_cache, distinct_id, properties, cohort_properties
+    property,
+    flags_by_key,
+    evaluation_cache,
+    distinct_id,
+    properties,
+    cohort_properties,
+    device_id=None,
 ):
     """
     Evaluate a flag dependency property according to the dependency chain algorithm.
@@ -80,6 +86,7 @@ def evaluate_flag_dependency(
         distinct_id: The distinct ID being evaluated
         properties: Person properties for evaluation
         cohort_properties: Cohort properties for evaluation
+        device_id: The device ID for bucketing (optional)
 
     Returns:
         bool: True if all dependencies in the chain evaluate to True, False otherwise
@@ -131,6 +138,7 @@ def evaluate_flag_dependency(
                             cohort_properties,
                             flags_by_key,
                             evaluation_cache,
+                            device_id=device_id,
                         )
                         evaluation_cache[dep_flag_key] = dep_result
                     except InconclusiveMatchError as e:
@@ -222,16 +230,32 @@ def match_feature_flag_properties(
     cohort_properties=None,
     flags_by_key=None,
     evaluation_cache=None,
+    device_id=None,
+    skip_bucketing_identifier=False,
 ) -> FlagValue:
-    flag_conditions = (flag.get("filters") or {}).get("groups") or []
+    flag_filters = flag.get("filters") or {}
+    flag_conditions = flag_filters.get("groups") or []
     is_inconclusive = False
     cohort_properties = cohort_properties or {}
     # Some filters can be explicitly set to null, which require accessing variants like so
-    flag_variants = ((flag.get("filters") or {}).get("multivariate") or {}).get(
-        "variants"
-    ) or []
+    flag_variants = (flag_filters.get("multivariate") or {}).get("variants") or []
     valid_variant_keys = [variant["key"] for variant in flag_variants]
 
+    # Determine the hashing identifier based on bucketing_identifier setting
+    # For group flags, skip_bucketing_identifier is True and we always use the passed identifier
+    if skip_bucketing_identifier:
+        hashing_identifier = distinct_id
+    else:
+        bucketing_identifier = flag_filters.get("bucketing_identifier")
+        if bucketing_identifier == "device_id":
+            if not device_id:
+                raise InconclusiveMatchError(
+                    "Flag requires device_id for bucketing but none was provided"
+                )
+            hashing_identifier = device_id
+        else:
+            hashing_identifier = distinct_id
+
     for condition in flag_conditions:
         try:
             # if any one condition resolves to True, we can shortcircuit and return
@@ -244,12 +268,14 @@ def match_feature_flag_properties(
                 cohort_properties,
                 flags_by_key,
                 evaluation_cache,
+                hashing_identifier=hashing_identifier,
+                device_id=device_id,
             ):
                 variant_override = condition.get("variant")
                 if variant_override and variant_override in valid_variant_keys:
                     variant = variant_override
                 else:
-                    variant = get_matching_variant(flag, distinct_id)
+                    variant = get_matching_variant(flag, hashing_identifier)
                 return variant or True
         except RequiresServerEvaluation:
             # Static cohort or other missing server-side data - must fallback to API
@@ -277,7 +303,13 @@ def is_condition_match(
     cohort_properties,
     flags_by_key=None,
     evaluation_cache=None,
+    hashing_identifier=None,
+    device_id=None,
 ) -> bool:
+    # Use hashing_identifier if provided, otherwise fall back to distinct_id
+    if hashing_identifier is None:
+        hashing_identifier = distinct_id
+
     rollout_percentage = condition.get("rollout_percentage")
     if len(condition.get("properties") or []) > 0:
         for prop in condition.get("properties"):
@@ -290,6 +322,7 @@ def is_condition_match(
                     flags_by_key,
                     evaluation_cache,
                     distinct_id,
+                    device_id=device_id,
                 )
             elif property_type == "flag":
                 matches = evaluate_flag_dependency(
@@ -299,6 +332,7 @@ def is_condition_match(
                     distinct_id,
                     properties,
                     cohort_properties,
+                    device_id=device_id,
                 )
             else:
                 matches = match_property(prop, properties)
@@ -308,9 +342,9 @@ def is_condition_match(
         if rollout_percentage is None:
             return True
 
-    if rollout_percentage is not None and _hash(feature_flag["key"], distinct_id) > (
-        rollout_percentage / 100
-    ):
+    if rollout_percentage is not None and _hash(
+        feature_flag["key"], hashing_identifier
+    ) > (rollout_percentage / 100):
         return False
 
     return True
@@ -454,6 +488,7 @@ def match_cohort(
     flags_by_key=None,
     evaluation_cache=None,
     distinct_id=None,
+    device_id=None,
 ) -> bool:
     # Cohort properties are in the form of property groups like this:
     # {
@@ -478,6 +513,7 @@ def match_cohort(
         flags_by_key,
         evaluation_cache,
         distinct_id,
+        device_id=device_id,
     )
 
 
@@ -488,6 +524,7 @@ def match_property_group(
     flags_by_key=None,
     evaluation_cache=None,
     distinct_id=None,
+    device_id=None,
 ) -> bool:
     if not property_group:
         return True
@@ -512,6 +549,7 @@ def match_property_group(
                     flags_by_key,
                     evaluation_cache,
                     distinct_id,
+                    device_id=device_id,
                 )
                 if property_group_type == "AND":
                     if not matches:
@@ -545,6 +583,7 @@ def match_property_group(
                         flags_by_key,
                         evaluation_cache,
                         distinct_id,
+                        device_id=device_id,
                     )
                 elif prop.get("type") == "flag":
                     matches = evaluate_flag_dependency(
@@ -554,6 +593,7 @@ def match_property_group(
                         distinct_id,
                         property_values,
                         cohort_properties,
+                        device_id=device_id,
                     )
                 else:
                     matches = match_property(prop, property_values)