lduser

package
v2.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 30, 2022 License: Apache-2.0 Imports: 5 Imported by: 24

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 added in v2.1.0 

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/home/flags/targeting-users#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 added in v2.2.0 

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 deprecated 

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 added in v2.2.0 

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/home/flags/targeting-users#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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.