Documentation

Overview

    Package lduser defines the LaunchDarkly SDK model for user properties.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func ErrMissingKey

    func ErrMissingKey() error

      ErrMissingKey returns the standard error value that is used if you try to unmarshal a user from JSON and the "key" property is either absent or null. This is distinguished from other kinds of unmarshaling errors (such as trying to set a string property to a non-string value) in order to support use cases where incomplete data needs to be treated differently from malformed data.

      LaunchDarkly does allow a user to have an empty string ("") as a key in some cases, but this is discouraged since analytics events will not work properly without unique user keys.

      Types

      type User

      type User struct {
      	// contains filtered or unexported fields
      }

        A User contains specific attributes of a user browsing your site. The only mandatory property is the Key, which must uniquely identify each user. For authenticated users, this may be a username or e-mail address. For anonymous users, this could be an IP address or session ID.

        Besides the mandatory key, User supports two kinds of optional attributes: interpreted attributes (e.g. IP and Country) and custom attributes. LaunchDarkly can parse interpreted attributes and attach meaning to them. For example, from an IP address, LaunchDarkly can do a geo IP lookup and determine the user's country.

        Custom attributes are not parsed by LaunchDarkly. They can be used in custom rules-- for example, a custom attribute such as "customer_ranking" can be used to launch a feature to the top 10% of users on a site.

        User fields are immutable and can be accessed only via getter methods. To construct a User, use either a simple constructor (NewUser, NewAnonymousUser) or the builder pattern with NewUserBuilder.

        func NewAnonymousUser

        func NewAnonymousUser(key string) User

          NewAnonymousUser creates a new anonymous user identified by the given key.

          func NewUser

          func NewUser(key string) User

            NewUser creates a new user identified by the given key.

            func (User) Equal

            func (u User) Equal(other User) bool

              Equal tests whether two users have equal attributes.

              Regular struct equality comparison is not allowed for User because it can contain slices and maps. This method is faster than using reflect.DeepEqual(), and also correctly ignores insignificant differences in the internal representation of the attributes.

              func (User) GetAllCustom

              func (u User) GetAllCustom() ldvalue.Value

                GetAllCustom returns all of the user's custom attributes.

                These are represented as a Value that is either an object (with a key-value pair for each attribute) or Null() if there are no custom attributes.

                func (User) GetAllCustomMap

                func (u User) GetAllCustomMap() ldvalue.ValueMap

                  GetAllCustomMap returns all of the user's custom attributes as an immutable ValueMap.

                  func (User) GetAnonymous

                  func (u User) GetAnonymous() bool

                    GetAnonymous returns the anonymous attribute of the user.

                    If a user is anonymous, the user key will not appear on your LaunchDarkly dashboard.

                    func (User) GetAnonymousOptional

                    func (u User) GetAnonymousOptional() (bool, bool)

                      GetAnonymousOptional returns the anonymous attribute of the user, with a second value indicating whether that attribute was defined for the user or not.

                      func (User) GetAttribute

                      func (u User) GetAttribute(attribute UserAttribute) ldvalue.Value

                        GetAttribute returns one of the user's attributes.

                        The attribute parameter specifies which attribute to get. To get a custom attribute rather than one of the built-in ones identified by the UserAttribute constants, simply cast any string to the UserAttribute type.

                        If no value has been set for this attribute, GetAttribute returns ldvalue.Null().

                        func (User) GetAvatar

                        func (u User) GetAvatar() ldvalue.OptionalString

                          GetAvatar returns the avatar URL attribute of the user, if any.

                          func (User) GetCountry

                          func (u User) GetCountry() ldvalue.OptionalString

                            GetCountry returns the country attribute of the user, if any.

                            func (User) GetCustom

                            func (u User) GetCustom(attribute string) (ldvalue.Value, bool)

                              GetCustom returns a custom attribute of the user by name. The boolean second return value indicates whether any value was set for this attribute or not.

                              The value is returned using the ldvalue.Value type, which can contain any type supported by JSON: boolean, number, string, array (slice), or object (map). Use Value methods to access the value as the desired type, rather than casting it. If the attribute did not exist, the value will be ldvalue.Null() and the second return value will be false.

                              func (User) GetEmail

                              func (u User) GetEmail() ldvalue.OptionalString

                                GetEmail returns the email address attribute of the user, if any.

                                func (User) GetFirstName

                                func (u User) GetFirstName() ldvalue.OptionalString

                                  GetFirstName returns the first name attribute of the user, if any.

                                  func (User) GetIP

                                  func (u User) GetIP() ldvalue.OptionalString

                                    GetIP returns the IP address attribute of the user, if any.

                                    func (User) GetKey

                                    func (u User) GetKey() string

                                      GetKey gets the unique key of the user.

                                      func (User) GetLastName

                                      func (u User) GetLastName() ldvalue.OptionalString

                                        GetLastName returns the last name attribute of the user, if any.

                                        func (User) GetName

                                        func (u User) GetName() ldvalue.OptionalString

                                          GetName returns the full name attribute of the user, if any.

                                          func (User) GetSecondaryKey

                                          func (u User) GetSecondaryKey() ldvalue.OptionalString

                                            GetSecondaryKey returns the secondary key of the user, if any.

                                            This affects feature flag targeting (https://docs.launchdarkly.com/docs/targeting-users#section-targeting-rules-based-on-user-attributes) as follows: if you have chosen to bucket users by a specific attribute, the secondary key (if set) is used to further distinguish between users who are otherwise identical according to that attribute.

                                            func (User) HasPrivateAttributes

                                            func (u User) HasPrivateAttributes() bool

                                              HasPrivateAttributes returns true if any attribute were marked private or this user.

                                              func (User) IsPrivateAttribute

                                              func (u User) IsPrivateAttribute(attribute UserAttribute) bool

                                                IsPrivateAttribute tests whether the given attribute is private for this user.

                                                The attribute name can either be a built-in attribute like NameAttribute or a custom one.

                                                func (User) MarshalJSON

                                                func (u User) MarshalJSON() ([]byte, error)

                                                  MarshalJSON provides JSON serialization for User when using json.MarshalJSON.

                                                  This is LaunchDarkly's standard JSON representation for user properties, in which all of the built-in user attributes are at the top level along with a "custom" property that is an object containing all of the custom attributes.

                                                  In order for the representation to be as compact as possible, any top-level attributes for which no value has been set (as opposed to being set to an empty string) will be completely omitted, rather than including "attributeName":null in the JSON output. Similarly, if there are no custom attributes, there will be no "custom" property (rather than "custom":{}). This distinction does not matter to LaunchDarkly services-- they will treat an explicit null value in JSON data the same as an unset attribute, and treat an omitted "custom" the same as an empty "custom" map.

                                                  func (*User) ReadFromJSONReader

                                                  func (u *User) ReadFromJSONReader(r *jreader.Reader)

                                                    ReadFromJSONReader provides JSON deserialization for use with the jsonstream API.

                                                    This implementation is used by the SDK in cases where it is more efficient than JSON.Unmarshal. See https://github.com/launchdarkly/go-jsonstream for more details.

                                                    func (User) String

                                                    func (u User) String() string

                                                      String returns a simple string representation of a user.

                                                      This currently uses the same JSON string representation as User.MarshalJSON(). Do not rely on this specific behavior of String(); it is intended for convenience in debugging.

                                                      func (*User) UnmarshalJSON

                                                      func (u *User) UnmarshalJSON(data []byte) error

                                                        UnmarshalJSON provides JSON deserialization for User when using json.UnmarshalJSON.

                                                        This is LaunchDarkly's standard JSON representation for user properties, in which all of the built-in properties are at the top level along with a "custom" property that is an object containing all of the custom properties.

                                                        Any property that is either completely omitted or has a null value is ignored and left in an unset state, except for "key". All users must have a key (even if it is ""), so an omitted or null "key" property causes the error ErrMissingKey().

                                                        Trying to unmarshal any non-struct value, including a JSON null, into a User will return a json.UnmarshalTypeError. If you want to unmarshal optional user data that might be null, use *User instead of User.

                                                        func (User) WriteToJSONBuffer

                                                        func (u User) WriteToJSONBuffer(j *jsonstream.JSONBuffer)

                                                          WriteToJSONBuffer provides JSON serialization for use with the deprecated jsonstream API.

                                                          Deprecated: this method is provided for backward compatibility. The LaunchDarkly SDK no longer uses this API; instead it uses the newer https://github.com/launchdarkly/go-jsonstream.

                                                          func (User) WriteToJSONWriter

                                                          func (u User) WriteToJSONWriter(w *jwriter.Writer)

                                                            WriteToJSONWriter provides JSON serialization for use with the jsonstream API.

                                                            This implementation is used by the SDK in cases where it is more efficient than JSON.Marshal. See https://github.com/launchdarkly/go-jsonstream for more details.

                                                            type UserAttribute

                                                            type UserAttribute string

                                                              UserAttribute is a string type representing the name of a user attribute.

                                                              Constants like KeyAttribute describe all of the built-in attributes; you may also cast any string to UserAttribute when referencing a custom attribute name.

                                                              const (
                                                              	// KeyAttribute is the standard attribute name corresponding to User.GetKey().
                                                              	KeyAttribute UserAttribute = "key"
                                                              	// SecondaryKeyAttribute is the standard attribute name corresponding to User.GetSecondaryKey().
                                                              	SecondaryKeyAttribute UserAttribute = "secondary"
                                                              	// IPAttribute is the standard attribute name corresponding to User.GetIP().
                                                              	IPAttribute UserAttribute = "ip"
                                                              	// CountryAttribute is the standard attribute name corresponding to User.GetCountry().
                                                              	CountryAttribute UserAttribute = "country"
                                                              	// EmailAttribute is the standard attribute name corresponding to User.GetEmail().
                                                              	EmailAttribute UserAttribute = "email"
                                                              	// FirstNameAttribute is the standard attribute name corresponding to User.GetFirstName().
                                                              	FirstNameAttribute UserAttribute = "firstName"
                                                              	// LastNameAttribute is the standard attribute name corresponding to User.GetLastName().
                                                              	LastNameAttribute UserAttribute = "lastName"
                                                              	// AvatarAttribute is the standard attribute name corresponding to User.GetAvatar().
                                                              	AvatarAttribute UserAttribute = "avatar"
                                                              	// NameAttribute is the standard attribute name corresponding to User.GetName().
                                                              	NameAttribute UserAttribute = "name"
                                                              	// AnonymousAttribute is the standard attribute name corresponding to User.GetAnonymous().
                                                              	AnonymousAttribute UserAttribute = "anonymous"
                                                              )

                                                              type UserBuilder

                                                              type UserBuilder interface {
                                                              	// Key changes the unique key for the user being built.
                                                              	Key(value string) UserBuilder
                                                              
                                                              	// Secondary sets the secondary key attribute for the user being built.
                                                              	//
                                                              	// This affects feature flag targeting
                                                              	// (https://docs.launchdarkly.com/docs/targeting-users#section-targeting-rules-based-on-user-attributes)
                                                              	// as follows: if you have chosen to bucket users by a specific attribute, the secondary key (if set)
                                                              	// is used to further distinguish between users who are otherwise identical according to that attribute.
                                                              	Secondary(value string) UserBuilderCanMakeAttributePrivate
                                                              
                                                              	// IP sets the IP address attribute for the user being built.
                                                              	IP(value string) UserBuilderCanMakeAttributePrivate
                                                              
                                                              	// Country sets the country attribute for the user being built.
                                                              	Country(value string) UserBuilderCanMakeAttributePrivate
                                                              
                                                              	// Email sets the email attribute for the user being built.
                                                              	Email(value string) UserBuilderCanMakeAttributePrivate
                                                              
                                                              	// FirstName sets the first name attribute for the user being built.
                                                              	FirstName(value string) UserBuilderCanMakeAttributePrivate
                                                              
                                                              	// LastName sets the last name attribute for the user being built.
                                                              	LastName(value string) UserBuilderCanMakeAttributePrivate
                                                              
                                                              	// Avatar sets the avatar URL attribute for the user being built.
                                                              	Avatar(value string) UserBuilderCanMakeAttributePrivate
                                                              
                                                              	// Name sets the full name attribute for the user being built.
                                                              	Name(value string) UserBuilderCanMakeAttributePrivate
                                                              
                                                              	// Anonymous sets the anonymous attribute for the user being built.
                                                              	//
                                                              	// If a user is anonymous, the user key will not appear on your LaunchDarkly dashboard.
                                                              	Anonymous(value bool) UserBuilder
                                                              
                                                              	// Custom sets a custom attribute for the user being built.
                                                              	//
                                                              	//     user := NewUserBuilder("user-key").
                                                              	//         Custom("custom-attr-name", ldvalue.String("some-string-value")).AsPrivateAttribute().
                                                              	//         Build()
                                                              	Custom(attribute string, value ldvalue.Value) UserBuilderCanMakeAttributePrivate
                                                              
                                                              	// CustomAll sets all of the user's custom attributes at once from a ValueMap.
                                                              	//
                                                              	// UserBuilder has copy-on-write behavior to make this method efficient: if you do not make any
                                                              	// changes to custom attributes after this, it reuses the original map rather than allocating a
                                                              	// new one.
                                                              	CustomAll(ldvalue.ValueMap) UserBuilderCanMakeAttributePrivate
                                                              
                                                              	// SetAttribute sets any attribute of the user being built, specified as a UserAttribute, to a value
                                                              	// of type ldvalue.Value.
                                                              	//
                                                              	// This method corresponds to the GetAttribute method of User. It is intended for cases where user
                                                              	// properties are being constructed generically, such as from a list of key-value pairs. Since not
                                                              	// all attributes have the same semantics, its behavior is as follows:
                                                              	//
                                                              	// 1. For built-in attributes, if the value is not of a type that is supported for that attribute,
                                                              	// the method has no effect. For Key, the only supported type is string; for Anonymous, the
                                                              	// supported types are boolean or null; and for all other built-ins, the supported types are
                                                              	// string or null. Custom attributes may be of any type.
                                                              	//
                                                              	// 2. Setting an attribute to null (ldvalue.Null() or ldvalue.Value{}) is the same as the attribute
                                                              	// not being set in the first place.
                                                              	//
                                                              	// 3. The method always returns the type UserBuilderCanMakeAttributePrivate, so that you can make
                                                              	// the attribute private if that is appropriate by calling AsPrivateAttribute(). For attributes
                                                              	// that cannot be made private (Key and Anonymous), calling AsPrivateAttribute() on this return
                                                              	// value will have no effect.
                                                              	SetAttribute(attribute UserAttribute, value ldvalue.Value) UserBuilderCanMakeAttributePrivate
                                                              
                                                              	// Build creates a User from the current UserBuilder properties.
                                                              	//
                                                              	// The User is independent of the UserBuilder once you have called Build(); modifying the UserBuilder
                                                              	// will not affect an already-created User.
                                                              	Build() User
                                                              }

                                                                UserBuilder is a mutable object that uses the Builder pattern to specify properties for a User. This is the preferred method for constructing a User; direct access to User fields will be removed in a future version.

                                                                Obtain an instance of UserBuilder by calling NewUserBuilder, then call setter methods such as Name to specify any additional user properties, then call Build() to construct the User. All of the UserBuilder setters return a reference the same builder, so they can be chained together:

                                                                user := NewUserBuilder("user-key").Name("Bob").Email("test@example.com").Build()
                                                                

                                                                Setters for user attributes that can be designated private return the type UserBuilderCanMakeAttributePrivate, so you can chain the AsPrivateAttribute method:

                                                                user := NewUserBuilder("user-key").Name("Bob").AsPrivateAttribute().Build() // Name is now private
                                                                

                                                                A UserBuilder should not be accessed by multiple goroutines at once.

                                                                This is defined as an interface rather than a concrete type only for syntactic convenience (see UserBuilderCanMakeAttributePrivate). Applications should not implement this interface since the package may add methods to it in the future.

                                                                func NewUserBuilder

                                                                func NewUserBuilder(key string) UserBuilder

                                                                  NewUserBuilder constructs a new UserBuilder, specifying the user key.

                                                                  For authenticated users, the key may be a username or e-mail address. For anonymous users, this could be an IP address or session ID.

                                                                  func NewUserBuilderFromUser

                                                                  func NewUserBuilderFromUser(fromUser User) UserBuilder

                                                                    NewUserBuilderFromUser constructs a new UserBuilder, copying all attributes from an existing user. You may then call setter methods on the new UserBuilder to modify those attributes.

                                                                    Custom attributes, and the set of attribute names that are private, are implemented internally as maps. Since the User struct does not expose these maps, they are in effect immutable and will be reused from the original User rather than copied whenever possible. The UserBuilder has copy-on-write behavior so that it only makes copies of these data structures if you actually modify them.

                                                                    type UserBuilderCanMakeAttributePrivate

                                                                    type UserBuilderCanMakeAttributePrivate interface {
                                                                    	UserBuilder
                                                                    
                                                                    	// AsPrivateAttribute marks the last attribute that was set on this builder as being a private
                                                                    	// attribute: that is, its value will not be sent to LaunchDarkly.
                                                                    	//
                                                                    	// This action only affects analytics events that are generated by this particular user object. To
                                                                    	// mark some (or all) user attributes as private for all users, use the Config properties
                                                                    	// PrivateAttributeName and AllAttributesPrivate.
                                                                    	//
                                                                    	// Most attributes can be made private, but Key and Anonymous cannot. This is enforced by the
                                                                    	// compiler, since the builder methods for attributes that can be made private are the only ones
                                                                    	// that return UserBuilderCanMakeAttributePrivate; therefore, you cannot write an expression like
                                                                    	// NewUserBuilder("user-key").AsPrivateAttribute().
                                                                    	//
                                                                    	// In this example, FirstName and LastName are marked as private, but Country is not:
                                                                    	//
                                                                    	//     user := NewUserBuilder("user-key").
                                                                    	//         FirstName("Pierre").AsPrivateAttribute().
                                                                    	//         LastName("Menard").AsPrivateAttribute().
                                                                    	//         Country("ES").
                                                                    	//         Build()
                                                                    	AsPrivateAttribute() UserBuilder
                                                                    
                                                                    	// AsNonPrivateAttribute marks the last attribute that was set on this builder as not being a
                                                                    	// private attribute: that is, its value will be sent to LaunchDarkly and can appear on the dashboard.
                                                                    	//
                                                                    	// This is the opposite of AsPrivateAttribute(), and has no effect unless you have previously called
                                                                    	// AsPrivateAttribute() for the same attribute on the same user builder. For more details, see
                                                                    	// AsPrivateAttribute().
                                                                    	AsNonPrivateAttribute() UserBuilder
                                                                    }

                                                                      UserBuilderCanMakeAttributePrivate is an extension of UserBuilder that allows attributes to be made private via the AsPrivateAttribute() method. All UserBuilderCanMakeAttributePrivate setter methods are the same as UserBuilder, and apply to the original builder.

                                                                      UserBuilder setter methods for attributes that can be made private always return this interface. See AsPrivateAttribute for details.