feat: add device_id to flags request payload

CHANGELOG.md

@@ -1,3 +1,9 @@
+# 7.6.0 - 2026-01-12
+
+feat: add device_id to flags request payload
+
+Add device_id parameter to all feature flag methods, allowing the server to track device identifiers for flag evaluation. The device_id can be passed explicitly or set via context using `set_context_device_id()`.
+
 # 7.5.1 - 2026-01-07
 
 fix: avoid return from finally block to fix Python 3.14 SyntaxWarning (#361) - thanks @jodal

posthog/__init__.py

@@ -23,6 +23,9 @@
 from posthog.contexts import (
     set_code_variables_mask_patterns_context as inner_set_code_variables_mask_patterns_context,
 )
+from posthog.contexts import (
+    set_context_device_id as inner_set_context_device_id,
+)
 from posthog.contexts import (
     set_context_session as inner_set_context_session,
 )
@@ -133,6 +136,26 @@ def set_context_session(session_id: str):
     return inner_set_context_session(session_id)
 
 
+def set_context_device_id(device_id: str):
+    """
+    Set the device ID for the current context, associating all feature flag requests
+    in this or child contexts with the given device ID.
+
+    Args:
+        device_id: The device ID to associate with the current context and its children
+
+    Examples:
+        ```python
+        from posthog import set_context_device_id
+        set_context_device_id("device_123")
+        ```
+
+    Category:
+        Contexts
+    """
+    return inner_set_context_device_id(device_id)
+
+
 def identify_context(distinct_id: str):
     """
     Identify the current context with a distinct ID.
@@ -483,6 +506,7 @@ def feature_enabled(
     only_evaluate_locally=False,  # type: bool
     send_feature_flag_events=True,  # type: bool
     disable_geoip=None,  # type: Optional[bool]
+    device_id=None,  # type: Optional[str]
 ):
     # type: (...) -> bool
     """
@@ -522,6 +546,7 @@ def feature_enabled(
         only_evaluate_locally=only_evaluate_locally,
         send_feature_flag_events=send_feature_flag_events,
         disable_geoip=disable_geoip,
+        device_id=device_id,
     )
 
 
@@ -534,6 +559,7 @@ def get_feature_flag(
     only_evaluate_locally=False,  # type: bool
     send_feature_flag_events=True,  # type: bool
     disable_geoip=None,  # type: Optional[bool]
+    device_id=None,  # type: Optional[str]
 ) -> Optional[FeatureFlag]:
     """
     Get feature flag variant for users. Used with experiments.
@@ -572,6 +598,7 @@ def get_feature_flag(
         only_evaluate_locally=only_evaluate_locally,
         send_feature_flag_events=send_feature_flag_events,
         disable_geoip=disable_geoip,
+        device_id=device_id,
     )
 
 
@@ -582,6 +609,7 @@ def get_all_flags(
     group_properties=None,  # type: Optional[dict]
     only_evaluate_locally=False,  # type: bool
     disable_geoip=None,  # type: Optional[bool]
+    device_id=None,  # type: Optional[str]
 ) -> Optional[dict[str, FeatureFlag]]:
     """
     Get all flags for a given user.
@@ -614,6 +642,7 @@ def get_all_flags(
         group_properties=group_properties or {},
         only_evaluate_locally=only_evaluate_locally,
         disable_geoip=disable_geoip,
+        device_id=device_id,
     )
 
 
@@ -626,6 +655,7 @@ def get_feature_flag_result(
     only_evaluate_locally=False,
     send_feature_flag_events=True,
     disable_geoip=None,  # type: Optional[bool]
+    device_id=None,  # type: Optional[str]
 ):
     # type: (...) -> Optional[FeatureFlagResult]
     """
@@ -657,6 +687,7 @@ def get_feature_flag_result(
         only_evaluate_locally=only_evaluate_locally,
         send_feature_flag_events=send_feature_flag_events,
         disable_geoip=disable_geoip,
+        device_id=device_id,
     )
 
 
@@ -670,6 +701,7 @@ def get_feature_flag_payload(
     only_evaluate_locally=False,
     send_feature_flag_events=True,
     disable_geoip=None,  # type: Optional[bool]
+    device_id=None,  # type: Optional[str]
 ) -> Optional[str]:
     return _proxy(
         "get_feature_flag_payload",
@@ -682,6 +714,7 @@ def get_feature_flag_payload(
         only_evaluate_locally=only_evaluate_locally,
         send_feature_flag_events=send_feature_flag_events,
         disable_geoip=disable_geoip,
+        device_id=device_id,
     )
 
 
@@ -712,6 +745,7 @@ def get_all_flags_and_payloads(
     group_properties=None,  # type: Optional[dict]
     only_evaluate_locally=False,
     disable_geoip=None,  # type: Optional[bool]
+    device_id=None,  # type: Optional[str]
 ) -> FlagsAndPayloads:
     return _proxy(
         "get_all_flags_and_payloads",
@@ -721,6 +755,7 @@ def get_all_flags_and_payloads(
         group_properties=group_properties or {},
         only_evaluate_locally=only_evaluate_locally,
         disable_geoip=disable_geoip,
+        device_id=device_id,
     )