Go Server SDK

How to install

Get the package from GitHub using go get.

Bash

go get github.com/fingerprintjs/go-sdk/v8

Initialize the client instance and use it to make API requests. You need to specify your secret API key and region (if it is not US/Global).

package main

import (
  "context"
  "fmt"
  "log"

  "github.com/fingerprintjs/go-sdk/v8"
)

func main() {
  client := fingerprint.New(
    fingerprint.WithAPIKey("SECRET_API_KEY"),
    // fingerprint.WithRegion(fingerprint.RegionEU),
  )

  // Search events, for example, by Visitor ID
  searchEventsOpts := fingerprint.NewSearchEventsRequest().
    VisitorID("VISITOR_ID").
    Limit(10)

  searchEventsResult, searchEventsHttpRes, searchErr :=
    client.SearchEvents(context.Background(), searchEventsOpts)
  if searchErr != nil {
    if errResp, ok := fingerprint.AsErrorResponse(searchErr); ok {
      log.Printf("Error %s: %v", errResp.Error.Code, errResp)
    }
    log.Fatal(searchErr)
  }
  fmt.Printf("Search events result: %v", searchEventsResult)
  fmt.Printf("Search events response: %v", searchEventsHttpRes)

  // Get a specific identification event
  event, eventHttpRes, eventErr :=
    client.GetEvent(context.Background(), "EVENT_ID")
  if eventErr != nil {
    if errResp, ok := fingerprint.AsErrorResponse(eventErr); ok {
      switch errResp.Error.Code {
      case fingerprint.ErrorCodeEventNotFound:
        log.Fatalf("Event not found")
      default:
        log.Printf("Error %s: %v", errResp.Error.Code, errResp)
      }
    }
    log.Fatal(eventErr)
  }
  fmt.Printf("Event: %v", event)
  fmt.Printf("Event response: %v", eventHttpRes)
}

Migration guide for Go SDK v8

Version 8 migrates the SDK from Server API v3 to v4. This is a breaking change. This section summarizes the most important changes from previous versions.

Module rename

The module path changed from github.com/fingerprintjs/fingerprint-pro-server-api-go-sdk/v7 to github.com/fingerprintjs/go-sdk/v8.

Bash

go get github.com/fingerprintjs/fingerprint-pro-server-api-go-sdk/v7
go get github.com/fingerprintjs/go-sdk/v8

import "github.com/fingerprintjs/fingerprint-pro-server-api-go-sdk/v7/sdk"
import "github.com/fingerprintjs/go-sdk/v8"

The v7 and v8 modules can be used side-by-side if you would like to migrate your codebase to the new version in stages.

Client construction

In v7, you created a context to pass your API key. In v8, you pass the API key when you create the client.

cfg := sdk.NewConfiguration() 
client := sdk.NewAPIClient(cfg) 
ctxWithAuth := context.WithValue(context.Background(), sdk.ContextAPIKey, sdk.APIKey{Key: "SECRET_API_KEY"}) 
client.FingerprintApi.GetEvent(ctxWithAuth, "EVENT_ID") 
client := fingerprint.New( 
  fingerprint.WithAPIKey("SECRET_API_KEY"), 
) 
client.GetEvent(context.Background(), "EVENT_ID") 

Get an event

GetEvent is now a method on the client, rather than nested in the FingerprintAPI interface, and returns *fingerprint.Event instead of EventsGetResponse. The event data structure is flatter. For example, the ID of the event, previously called the request ID, is now available at the top level as EventID, and identification fields moved from Products.Identification.Data to the top level.

resp, _, err := client.FingerprintApi.GetEvent(ctx, "EVENT_ID") 
requestID := resp.Products.Identification.Data.RequestId 
visitorID := resp.Products.Identification.Data.VisitorId 
event, _, err := client.GetEvent(context.Background(), "EVENT_ID") 
eventID := event.EventID 
visitorID := event.Identification.VisitorID 

Search events

SearchEvents uses a builder to construct the request rather than positional arguments and an options struct.

linkedID := "LINKED_ID"
resp, _, err := client.FingerprintApi.SearchEvents(ctx, 10, &sdk.FingerprintApiSearchEventsOpts{ 
  LinkedId: &linkedID, 
}) 
req := fingerprint.NewSearchEventsRequest().Limit(10).LinkedID("LINKED_ID") 
resp, _, err := client.SearchEvents(context.Background(), req) 

`GetVisits` replaced by `SearchEvents`

GetVisits has been removed. Use SearchEvents with VisitorID to query a visitor’s history.

resp, _, err := client.FingerprintApi.GetVisits(ctx, "VISITOR_ID") 
req := fingerprint.NewSearchEventsRequest().VisitorID("VISITOR_ID") 
resp, _, err := client.SearchEvents(context.Background(), req) 

Sealed results

UnsealEventsResponse is now part of the main fingerprint package instead of a separate sealed subpackage.

events, err := sealed.UnsealEventsResponse(sealedData, []sealed.DecryptionKey{ 
  {Key: key, Algorithm: sealed.AlgorithmAES256GCM}, 
}) 
events, err := fingerprint.UnsealEventsResponse(sealedData, []fingerprint.DecryptionKey{ 
  {Key: key, Algorithm: fingerprint.AlgorithmAES256GCM}, 
}) 

Error handling

Use fingerprint.AsErrorResponse to inspect errors. It returns a structured response with Error.Code and Error.Message. SDK calls also return an *http.Response, which you can read to use the raw response body when handling errors.

var apiErr sdk.ApiError
if errors.As(err, &apiErr) { 
  log.Printf("Error %s: %v", apiErr.Code(), apiErr.Error()) 
} 
if errResp, ok := fingerprint.AsErrorResponse(err); ok { 
  log.Printf("Error %s: %s", errResp.Error.Code, errResp.Error.Message) 
} 

Handling sealed client results from a v3 JavaScript agent

Go SDK v8 will fail to deserialize the decrypted payload of a sealed client result sent by a v3 JavaScript agent into an Event because the payload is an EventsGetResponse (i.e., the v3 event format), not an Event. To upgrade to Go SDK v8 without requiring a concurrent upgrade to the v4 JavaScript agent, you can fall back to using the Server API if unsealing the sealed client results fails. To enable this fallback path, your frontend must send the event ID alongside the sealed client results, as recommended by the sealed client results guide.

// Partial example (imports omitted).
func getEvent(
  client *fingerprint.Client,
  sealedResult []byte,
  eventID string,
  keys []fingerprint.DecryptionKey,
) (*fingerprint.Event, error) {
  // First, decrypt the sealed results
  sealedResultPayload, err := fingerprint.Unseal(sealedResult, keys)
  if err != nil {
    return nil, err
  }

  // Next, attempt to deserialize the payload into an event
  var sealedResultEvent fingerprint.Event
  err = json.Unmarshal(sealedResultPayload, &sealedResultEvent)
  if err == nil {
    return &sealedResultEvent, nil
  }

  // Deserialization failed. Fall back to the Server API using the event ID
  // sent alongside the client sealed results.
  log.Printf("Could not deserialize unsealed payload as a v4 Event, falling back to Server API: %v", err)
  serverAPIEvent, _, err := client.GetEvent(context.Background(), eventID)
  return serverAPIEvent, err
}

Documentation

You can find the full documentation in the official GitHub repository. The repository also contains an example app demonstrating the usage of the library.

JavaScript Agent

Server API

Automation Intelligence API

Policy and Upgrades

Device Reputation Network API

Management API

Server SDKs

How to install

Migration guide for Go SDK v8

Module rename

Client construction

Get an event

Search events

`GetVisits` replaced by `SearchEvents`

Sealed results

Error handling

Handling sealed client results from a v3 JavaScript agent

Documentation

​How to install

​Migration guide for Go SDK v8

​Module rename

​Client construction

​Get an event

​Search events

​GetVisits replaced by SearchEvents

​Sealed results

​Error handling

​Handling sealed client results from a v3 JavaScript agent

​Documentation

How to install

Migration guide for Go SDK v8

Module rename

Client construction

Get an event

Search events

`GetVisits` replaced by `SearchEvents`

Sealed results

Error handling

Handling sealed client results from a v3 JavaScript agent

Documentation