NAV
Go

Introduction to the Go SDK

Welcome to the Flagship Go SDK documentation!

The following documentation helps you to run Flagship inside your Go app.

The SDK helps you :

App prerequisites

This SDK requires Go 1.12 version or later to work

Installation

Follow these steps to install the Go SDK

Install from github

To install from github, just run a go get to add the SDK to your GOPATH

go get github.com/abtasty/flagship-go-sdk

Install from source

To install from github, just run a go get to add the SDK to your GOPATH, and run a go install to add the library to your installed dependencies.

go get github.com/abtasty/flagship-go-sdk

cd $GOPATH/src/github.com/abtasty/flagship-go-sdk

go install

Install using go.mod

Add the Flaship SDK dependency to your go.mod file and

module mymodule

go 1.12

require (
	github.com/abtasty/flagship-go-sdk v1.0.0
)

If you are already using go.mod in your application you can run the following:

go mod edit -require github.com/abtasty/flagship-go-sdk@v1.0.0

Getting started

environmentID := "YOUR_FS_ENV_ID"

// 1. Initialize the SDK client in BUCKETING mode
fsClient := flagship.Start(environmentID, client.WithBucketing())

// Create visitor context (maybe from your database or data layer)
context := map[string]interface{}{
  "isVip": true,
  "age": 30,
  "name": "visitor",
}

// 2. Create a visitor
fsVisitor, err := fsClient.NewVisitor("visitor_id", context)

// 3. Synchronizes modifications (match campaign with visitor context)
fsVisitor := fsVisitor.SynchronizeModifications()

// 4. Get a specific modification value from Flagship, defaulting it to false and activating it for tracking
enableDiscount, err := fsVisitor.GetModificationBool("enableDiscount", false, true)

// 5. Use your modification inside your application logic
discount := 0
if enableDiscount {
  discount = 0.15
}

// 6. Later on, send a hit tracking to know that the visitor has converted
fsVisitor.SendHit(&tracking.TransactionHit{
  TransactionID: "YOUR_TRANSACTION_ID",
  Affiliation: "GOAL_NAME", // Your transaction goal name set in Flagship
  Revenue: 150.5,
})

Here is a simple code to initialize the client, create a visitor with a context, get a specific modification and send a hit tracking. This sample code does the following:

  1. Initialize the SDK client with your Flagship Environment ID

  2. Create a new visitor with a visitor ID and a context

  3. Synchronize your visitor modifications (get the targeted campaigns according to its context)

  4. Obtain a specific boolean modification value, defaulting it to false, and sending an activation hit to notify Flagship that the visitor has seen this modification

  5. Use this modification value inside your code to dynamically change your business logic

  6. Send a Transaction Hit to Flagship data collect to notify Flagship that the visitor has made a transaction

Initialize and start the library

Call the Start function from the flagship package to initialize and start the library.

// Using the Decision API (default)
fsClient := flagship.Start(environmentID)

// Using the Bucketing mode
fsClient := flagship.Start(environmentID, client.WithBucketing())

To initialize and start the library, just call the Start function of the flagship package, using the bucketing function builder if you want to use the bucketing mode

The start function return a Flagship client instance for your environment.

Parameter Type Description
envId String Environment id provided by Flagship.
optionBuilders Variadic functions Option builder functions.


func WithDecisionAPI(...apiOptionBuilder): Builder

Start Flagship SDK in DECISION API mode (which is the default). apiOptionBuilders functions allows you to customize the API engine.

Parameter Type Description
apiOptionBuilders Variadic functions option builder for the Bucketing.

func APIUrl(url string)

Set the Decision API URL for the DECISION API mode. Useful for debugging or using a different version of the Decision API

Parameter Type Description
url string The Decision API base URL


func WithBucketing(...bucketingOptionBuilder)

Start Flagship SDK in BUCKETING mode (client-side) instead of DECISION API mode bucketingOptionBuilder functions allows you to customize the bucketing engine

Parameter Type Description
bucketingOptionBuilders Variadic functions option builder for the Bucketing.

func PollingInterval(interval time.Duration)

Set the polling interval for the bucketing engine (set by default to 60 seconds)

Parameter Type Description
interval time.Duration The polling interval for the bucketing.


Flagship Mode


DECISION API Mode

When the SDK is running in DECISION_API MODE (default), the allocation and its targeting validation will take place on server side. Therefore each call to the method SynchronizeModifications to refresh the modifications will lead to an http request.

BUCKETING Mode

When the SDK is running in BUCKETING MODE, the SDK will download all the campaigns configurations at once in a single bucket file and will make the allocation and its targeting validation on client-side. This bucket file will be stored in cache and will be downloaded again if there are some modifications made on the Flagship interface when the specified polling interval fires.

Create a Visitor

Create a visitor with an ID and a Context

The visitor context is a property dataset which defines the current user of your app. This dataset is sent and used by the Flagship decision API as targeting for campaign allocation. For example, you could pass a VIP status in the context and then the decision API would enable or disable a specific feature flag.

// Create visitor context
context := map[string]interface{}{
  "isVip": true,
  "age": 30,
  "name": "visitor",
}
// Create a visitor
fsVisitor := fsClient.NewVisitor("visitor_id", context)

The SDK provides a method create a new visitor with an ID and a context.

The NewVisitor function takes the followin parameters:

Parameter Type Description
VisitorID string The ID of the visitor (must be unique for a visitor)
Context map[string]interface{} The context of the visitor. It should match those defined in your campaigns to target your users on it.

Updating the visitor Context

// Update a single key
fsVisitor.UpdateContextKey("vipUser", true)
fsVisitor.UpdateContextLey("age", 30)

// Update the whole context
newContext := map[string]interface{}{
  "isVip": true,
  "age": 30,
  "name": "visitor",
}
fsVisitor.UpdateContext(newContext)

The visitor context can be updated in case some context linked to your visitor has changed. The SDK provides 2 methods to change the visitor context:

UpdateContextKey(key string, value interface{})

This functions update the visitor context value matching the given key. A new context value associated with this key will be created if there is no previous matching value.

Parameter Type Description
key string key to associate with the following value
value interface{} new context value

UpdateContext(newContext map[string]interface{})

Parameter Type Description
newContext map[string]interface{} key to associate with the following value

Campaign integration

Synchronizing campaigns

fsVisitor.SynchronizeModifications()

Synchronizing campaign modifications allows you to automatically call the Flagship decision API (or bucketing file), which makes the allocation according to user context and gets all their modifications.

All the applicable modifications are stored in the SDK and are updated synchronously when SynchronizeModifications() is called.

This function has no parameters

Retrieving modifications

Once the campaign has been allocated and synchronized all the modifications are stored in the SDK. Then, you can retrieve them with the following functions:

discountName, err := fsVisitor.GetModificationString("discountName", "Black Friday", true);

// If there is not error (and if there is, your value will still be set to defaut), you can use your modification value in your business logic
discountValue := getDiscountFromDB(discountName)


Parameter Type Required Description
key String Yes key associated to the modification.
defaultValue String, Boolean, Float64 Yes default value returned when the key doesn’t match any modification value.
activate Boolean  No false by default Set this parameter to true to automatically report on our server that the current visitor has seen this modification. If false, call the activateModification() later.

Activating modifications

Once a modification has been printed on the screen for a user, you must send an activation event to tell Flagship that the user has seen this specific variation.

// Activate the modification automatically when retrieving it
color, err := Flagship.GetModificationString("discountName", "Black Friday", true)

// ---OR---

// Activate the modification later on manually
err := Flagship.ActivateModification("discountName")

func (v *FlagshipVisitor) ActivateModification(key string)

Parameter Type Description
key String key which identifies the modification

Hit Tracking

This section helps send tracking and learn how to build hits in order to aprove campaign goals.

The different types of Hits are:

They must all be built and sent with the following function:

func (v *FlagshipVisitor) SendHit(hit tracking.HitInterface) (err error)

Page

fsVisitor.SendHit(&tracking.PageHit{
  DocumentLocation: "http://localhost:8080",
})

This hit should be sent each time a visitor arrives on a new interface.

Hit parameter Type Required Description
DocumentLocation String Yes Name of the origin page

Transaction

This hit should be sent when a user complete a Transaction.

fsVisitor.SendHit(&tracking.TransactionHit{
  TransactionID: "YOUR_TRANSACTION_ID",
  Affiliation: "GOAL_NAME", // The goal name set in Flagship campaign
  Revenue: 100,
  Shipping: 10,
  Tax: 5,
  Currency: "EUR",
  CouponCode: "discount",
  PaymentMethod: "Card",
  ShippingMethod: "postal",
  ItemCount: 2,
})
Hit Parameter Type Required Description
TransactionId String Yes Transaction unique identifier.
Affiliation String Yes Transaction name. Name of the goal in the reporting.
Revenue Float64 No Total revenue associated with the transaction. This value should include any shipping or tax costs.
Shipping Float64 No Specifies the total shipping cost of the transaction.
ShippingMethod String No Specifies the shipping method of the transaction.
Tax Float64 No Specifies the total taxes of the transaction.
Currency String No Specifies the currency used for all transaction currency values. Value should be a valid ISO 4217 currency code.
PaymentMethod String No Specifies the payment method for the transaction.
ItemCount Int No Specifies the number of items for the transaction.
CouponCode String No Specifies the coupon code used by the customer for the transaction.

Item

fsVisitor.SendHit(&tracking.ItemHit{
  TransactionID: "YOUR_TRANSACTION_ID", // Must be the same as for the Transaction Hit
  Name: "t-shirt",
  Category: "Clothes",
  Code: "SN123456",
  Quantity: 5,
  Price: 25.4,
})

This hit is linked to a transaction. It must be send after the corresponding transaction.


class Item(transactionId: String, productName: String) : HitBuilder<Item>()

Hit Parameter Type Required  Description
TransactionId String Yes Transaction unique identifier.
Name String Yes Product name.
Price Float64 No Specifies the item price.
Code String No Specifies the item code or SKU.
Category String No Specifies the item category.
Quantity Int No Specifies the item quantity

Event

fsVisitor.SendHit(&tracking.EventHit{
  Action: "GOAL_NAME", // The event goal name set in the Flagship campaign
  Category: "Action Tracking",
  Label: "Event label",
  Value: 5,
})

This hit can be anything you want: for example a click or a newsletter subscription.

Hit Parameter Type Required  Description
Category String Yes category of the event (“Action Tracking” or “User Engagement”).
Action String Yes the event action.
Label String No label of the event.
Value Number No Specifies a value for this event. must be non-negative.

Common parameters for hits

These parameters can be sent with any type of hit.


Parameter Type Description
UserIP String optional User IP
ScreenResolution String optional Screen Resolution.
UserLanguage String optional User Language
CurrentSessionTimeStamp Int64 optional Current Session Timestamp
SessionNumber Int optional Session Number

Releases

Sources

Sources of the library SDK are available at : https://github.com/abtasty/flagship-go-sdk

Go