# README
go-client
The userup
go client package provides a convenience wrapper for the GRPC interface. It supplies common functionality and a flexible query interface to ease integration of the userservice package into your application.
Installation
Import the package into your project:
import (
userup "github.com/hillside-labs/userservice-go-sdk/go-client"
)
Usage
The userup
package provides a UserService
struct which can be used to interact with the userservice GRPC interface.
Simply supply it with the address of the userservice GRPC server
client, err := userup.NewClient("localhost:9000")
defer client.Close()
Creating a User
user := &userup.User{
Username: "jdoe2",
Attributes: map[string]interface{}{
"user_type": "admin",
"email": "[email protected]",
"ranking": 5,
},
}
ctx := context.Background()
userRet, err := client.AddUser(ctx, user)
Retrieve a User
user, err = client.GetUser(ctx, userId)
Update a User
user, err := client.UpdateUser(ctx, user)
Any attributes or traits specified in the user struct will be added/updated during this operation.
Add an Attribute/Trait to a User
Attribute
err = client.AddAttribute(ctx, user.Id, "user_type", "admin")
Trait
err = client.AddTrait(ctx, user.Id, "selected_value", "gibson")
Log an Event
// Initialize the logger
logger := userup.NewLogger(userup.NewLoggerConfig("https://userup.io/sample-client", client))
...
logger.LogEvent(context.Background(), user.Id, "io.userup.user.created", "user", strconv.FormatUint(user.Id, 10), user)
Query Usage
The Query
struct provides a flexible way to construct and execute queries in the userservice package. This is an experimental portion of the SDK and will likely change as it develops.
Creating a Query
To create a new query, you can simply initialize a Query
struct:
query := userservice.NewQuery()
Filtering Users on username
query := userup.Query{
Filter: map[string]userup.Condition{
"username": "jdoe2",
}
}
users, err := client.QueryUsers(ctx, &query)
Filtering with different operators
If no operator is specified, the default operator is $eq
equality. Other supported operators are
$gt
greater than$gte
greater than or equal to$lt
less than$lte
less than or equal to$ne
not equal$regex
regular expression$in
in$nin
not in$like
like$ilike
case insensitive like
query := userup.Query{
Filter: map[string]userup.Condition{
"id": map[string]interface{}{"$gte": float64(70)},
}
}
users, err := client.QueryUsers(ctx, &query)
Filtering users based on attributes value
query := userup.Query{
Joins: []userup.Join{
{
Table: "attributes",
On: "users.id = attributes.user_id",
Filter: map[string]userup.Condition{
"attributes": {
"alias": "dumbledore",
},
},
},
},
}
users, err := client.QueryUsers(ctx, &query)
Filtering with an OR condition
query := userup.Query{
Joins: []Join{
{
Table: "attributes",
On: "users.id = attributes.user_id",
Filter: map[string]Condition{
"attributes": {
"$or": []Condition{
{
"2fa": false,
},
{
"vip_level": float64(2),
},
},
},
},
},
},
}
Anonymous Sessions and Session Events
When a User is not known, Anonymous Sessions can be used to track activity and eventually resolve that activity back to a know/new User.
Add Session
In this example, we assume that an Anonymous ID has been created already. The data argument to the AddSession
call is meant to be an example. There is no structure prescribed for this data. This example draws inspiration from the Segment Identify Call.
sessionData := map[string]interface{}{
"channel": "browser",
"context": {
"ip": "8.8.8.8",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.115 Safari/537.36"
},
"attributes": {
"vendor_url": "levis.com",
"referrer_params": {
"utm_source": "promo_email",
"utm_medium": "email",
"utm_campaign": "feb24promo",
"utm_content": "greatjeans"
}
},
}
ctx := context.Background()
userup.AddSession(ctx, anonID, sessionData)
Session Events
// Initialize the logger
logger := userup.NewSessionLogger(userup.NewLoggerConfig("https://userup.io/sample-client", client))
...
logger.LogEvent(context.Background(), user.Id, "io.userup.user.created", "user", strconv.FormatUint(user.Id, 10), user)