Struct ContextBuilder

pub struct ContextBuilder { /* private fields */ }

Contains methods for building a Context with a specified key.

To define a multi-context (containing more than one kind) see MultiContextBuilder.

You may use these methods to set additional attributes and/or change the kind before calling ContextBuilder::build. If you do not change any values, the defaults for the Context are:

• its kind is “user”
• its key is set to whatever value you passed to ContextBuilder::new
• its anonymous attribute is false
• it has no values for any other attributes.

Implementations

impl ContextBuilder

pub fn new(key: impl Into<String>) -> Self

Create a new context builder with the provided “key” attribute.

pub fn kind(&mut self, kind: impl Into<String>) -> &mut Self

Sets the context’s “kind” attribute, which is “user” by default.

Validation rules are as follows:

• It may not be an empty string
• It may only contain letters, numbers, and the characters ., _, and -
• It cannot be “kind”
• It cannot be “multi”

If the value is invalid, you will receive an error when ContextBuilder::build is called.

To ensure that a given kind will be valid, you may use Kind::try_from and pass that here.

pub fn key(&mut self, key: impl Into<String>) -> &mut Self

Sets the Context’s key attribute. The provided key cannot be an empty string.

The key attribute can be referenced by flag rules, flag target lists, and segments.

pub fn name(&mut self, name: impl Into<String>) -> &mut Self

Sets the context’s “name” attribute.

This attribute is optional. It has the following special rules:

• Unlike most other attributes, it is always a string if it is specified.
• The LaunchDarkly dashboard treats this attribute as the preferred display name for users.

pub fn set_bool(&mut self, attribute_name: &str, value: bool) -> &mut Self

Sets an attribute to a boolean value.

For rules regarding attribute names and values, see ContextBuilder::set_value. This method is exactly equivalent to calling self.set_value(attribute_name, AttributeValue::Bool(value)).

pub fn set_float(&mut self, attribute_name: &str, value: f64) -> &mut Self

Sets an attribute to a f64 numeric value.

For rules regarding attribute names and values, see ContextBuilder::set_value. This method is exactly equivalent to calling self.set_value(attribute_name, AttributeValue::Number(value)).

Note: the LaunchDarkly model for feature flags and context attributes is based on JSON types, and does not distinguish between integer and floating-point types.

pub fn set_string( &mut self, attribute_name: &str, value: impl Into<String>, ) -> &mut Self

Sets an attribute to a string value.

For rules regarding attribute names and values, see ContextBuilder::set_value. This method is exactly equivalent to calling self.set_value(attribute_name, AttributeValue::String(value.to_string())).

pub fn set_value( &mut self, attribute_name: &str, value: AttributeValue, ) -> &mut Self

Sets the value of any attribute for the context.

This includes only attributes that are addressable in evaluations – not metadata such as private attributes. For example, if attribute_name is “privateAttributes”, you will be setting an attribute with that name which you can use in evaluations or to record data for your own purposes, but it will be unrelated to ContextBuilder::add_private_attribute.

If attribute_name is “privateAttributeNames”, it is ignored and no attribute is set.

This method uses the AttributeValue type to represent a value of any JSON type: null, boolean, number, string, array, or object. For all attribute names that do not have special meaning to LaunchDarkly, you may use any of those types. Values of different JSON types are always treated as different values: for instance, null, false, and the empty string “” are not the same, and the number 1 is not the same as the string “1”.

The following attribute names have special restrictions on their value types, and any value of an unsupported type will be ignored (leaving the attribute unchanged):

• “kind”, “key”: Must be a string. See ContextBuilder::kind and ContextBuilder::key.

• “name”: Must be a string. See ContextBuilder::name.

• “anonymous”: Must be a boolean. See ContextBuilder::anonymous.

The attribute name “_meta” is not allowed, because it has special meaning in the JSON schema for contexts; any attempt to set an attribute with this name has no effect.

Values that are JSON arrays or objects have special behavior when referenced in flag/segment rules.

For attributes that aren’t subject to the special restrictions mentioned above, a value of AttributeValue::Null is equivalent to removing any current non-default value of the attribute. Null is not a valid attribute value in the LaunchDarkly model; any expressions in feature flags that reference an attribute with a null value will behave as if the attribute did not exist.

pub fn try_set_value( &mut self, attribute_name: &str, value: AttributeValue, ) -> bool

Sets the value of any attribute for the context.

This is the same as ContextBuilder::set_value, except that it returns true for success, or false if the parameters violated one of the restrictions described for ContextBuilder::set_value (for instance, attempting to set “key” to a value that was not a string).

pub fn add_private_attribute<R: Into<Reference>>( &mut self, reference: R, ) -> &mut Self

Designates any number of context attributes as private: that is, their values will not be sent to LaunchDarkly.

See Reference for details on how to construct a valid reference.

This action only affects analytics events that involve this particular context. To mark some (or all) context attributes as private for all uses, use the overall event configuration for the SDK.

The attributes “kind” and “key”, and the metadata property set by ContextBuilder::anonymous, cannot be made private.

pub fn remove_private_attribute<R: Into<Reference>>( &mut self, reference: R, ) -> &mut Self

Remove any reference provided through ContextBuilder::add_private_attribute. If the reference was added more than once, this method will remove all instances of it.

pub fn anonymous(&mut self, value: bool) -> &mut Self

Sets whether the context is only intended for flag evaluations and should not be indexed by LaunchDarkly.

The default value is false, which means that this context represents an entity such as a user that you want to see on the LaunchDarkly dashboard.

Setting anonymous to true excludes this context from the database that is used by the dashboard. It does not exclude it from analytics event data, so it is not the same as making attributes private; all non-private attributes will still be included in events and data export.

This value is also addressable in evaluations as the attribute name “anonymous”.

pub fn build(&self) -> Result<Context, String>

Creates a context from the current builder’s properties.

The context is immutable and will not be affected by any subsequent actions on the builder.

It is possible to specify invalid attributes for a builder, such as an empty key. In those situations, an Err type will be returned.