Go Events SDK

This is the mParticle Go SDK for the server-based Events API - use it to send your data to the mParticle platform and off to 250+ integrations!

Getting Started

Get the Dependency

go get github.com/mParticle/mparticle-go-sdk/events

Import the events Package

import "github.com/mParticle/mparticle-go-sdk/events"

Create a Batch

All data that passes through mParticle does so in the form of a "batch." A batch describes identities, attributes, events, and other information related to a single user. This SDK lets you upload either single batches or multiple batches at a time.

The full schema of a batch is documented in the mParticle Events API overview. The models in this SDK directly match the JSON referenced in the overview.

batch := events.Batch{Environment: events.DevelopmentEnvironment} //or "ProductionEnvironment"

//set user identities
batch.UserIdentities = &events.UserIdentities{
    CustomerID: "go1234",
    Email:      "[email protected]",
}

//set device identities
batch.DeviceInfo = &events.DeviceInformation{
    IOSAdvertisingID: "607258d9-c28b-43ad-95ed-e9593025d5a1",
}

//set user attributes
batch.UserAttributes = make(map[string]interface{})
batch.UserAttributes["foo"] = "bar"
batch.UserAttributes["foo-array"] = []string{"bar1", "bar2"}

It's critical to include either user or device identities with your server-side data

Create Events

All mParticle events have a similar structure:

• event_type: this is the type of event, such as custom_event and commerce_event
• data: this contains common properties of all events, as well as properties specific to each event_type

The following are common properties that all events share, as represented by the CommonEventData struct:

{
    "event_id" : 6004677780660780000,
    "source_message_id" : "e8335d31-2031-4bff-afec-17ffc1784697",
    "session_id" : 4957918240501247982,
    "session_uuid" : "91b86d0c-86cb-4124-a8b2-edee107de454",
    "timestamp_unixtime_ms" : 1402521613976,
    "location" : {},
    "device_current_state" : {},
    "custom_attributes": {},
    "custom_flags": {}
}

The Go Events SDK represents this structure via an event and an event-data struct for each unique event type. For convenience, every event struct provides a constructor to autopopulate the correct event type and data object, for example NewCustomEvent(), NewScreenViewEvent(), and NewCommerceEvent():

Custom Events

customEvent := events.NewCustomEvent()
customEvent.Data.EventName = "My Custom Event Name"
customEvent.Data.CustomEventType = events.OtherCustomEventType
customEvent.Data.CustomAttributes = make(map[string]string)
customEvent.Data.CustomAttributes["foo"] = "bar"

Screen Events

screenEvent := events.NewScreenViewEvent()
screenEvent.Data.ScreenName = "My Screen Name"

Commerce Events

totalProductAmount := 123.12
product := events.Product{
    TotalProductAmount: &totalProductAmount,
    ID:                 "product-id",
    Name:               "product-name",
}
	
commerceEvent := events.NewCommerceEvent()
totalPurchaseAmount := 123.12
commerceEvent.Data.ProductAction = &events.ProductAction{
    Action:        events.PurchaseAction,
    TotalAmount:   &totalProductAmount,
    TransactionID: "foo-transaction-id",
    Products:      []events.Product{product},
}

Full Upload Example

The SDK supports both multi-batch ("bulk") or single-batch uploads:

package main

import (
	"context"
	"fmt"
	"github.com/mParticle/mparticle-go-sdk/events"
)

func main() {
	client := events.NewAPIClient(events.NewConfiguration())

	ctx := context.WithValue(
		context.Background(),
		events.ContextBasicAuth,
		events.BasicAuth{
			APIKey:    "REPLACE WITH API KEY",
			APISecret: "REPLACE WITH API SECRET",
		},
	)
	batch := events.Batch{Environment: events.DevelopmentEnvironment} //or "ProductionEnvironment"

	//set user identities
	batch.UserIdentities = &events.UserIdentities{
		CustomerID: "go1234",
		Email:      "[email protected]",
	}

	//set context
	batch.BatchContext = &events.BatchContext{
		//configure data plan
		DataPlan: &events.DataPlanContext{
			PlanID:      "freddy_s_plan",
			PlanVersion: 1,
		},
	}

	//set device identities
	batch.DeviceInfo = &events.DeviceInformation{
		IOSAdvertisingID: "607258d9-c28b-43ad-95ed-e9593025d5a1",
	}

	//set user attributes
	batch.UserAttributes = make(map[string]interface{})
	batch.UserAttributes["foo"] = "bar"
	batch.UserAttributes["foo-array"] = []string{"bar1", "bar2"}

	customEvent := events.NewCustomEvent()
	customEvent.Data.EventName = "My Custom Event Name"
	customEvent.Data.CustomEventType = events.OtherCustomEventType
	customEvent.Data.CustomAttributes = make(map[string]string)
	customEvent.Data.CustomAttributes["foo"] = "bar"

	screenEvent := events.NewScreenViewEvent()
	screenEvent.Data.ScreenName = "My Screen Name"

	totalProductAmount := 123.12
	product := events.Product{
		TotalProductAmount: &totalProductAmount,
		ID:                 "product-id",
		Name:               "product-name",
	}

	commerceEvent := events.NewCommerceEvent()
	totalPurchaseAmount := 123.12
	commerceEvent.Data.ProductAction = &events.ProductAction{
		Action:        events.PurchaseAction,
		TotalAmount:   &totalPurchaseAmount,
		TransactionID: "foo-transaction-id",
		Products:      []events.Product{product},
	}

	batch.Events = []events.Event{customEvent, screenEvent, commerceEvent}

	result, err := client.EventsAPI.UploadEvents(ctx, batch)
	if result != nil && result.StatusCode == 202 {
		fmt.Println("Upload successful")
	} else {
		fmt.Errorf(
			"Error while uploading!\nstatus: %v\nresponse body: %#v",
			err.(events.GenericError).Error(),
			err.(events.GenericError).Model())
	}
}