Go SDK

gomodvv1.3.1

Go SDK를 사용하면 Go 애플리케이션에서 Amplitude로 이벤트를 전송할 수 있습니다.

SDK 설치

종속성을 설치합니다.

bash

go get github.com/amplitude/analytics-go

SDK 초기화

어떠한 이벤트라도 계측하려면 먼저 SDK를 초기화해야 합니다. Amplitude 프로젝트의 API 키는 구성 struct를 생성합니다. 이 구성 struct를 사용하여 클라이언트 인터페이스를 구현하는 클라이언트 struct를 초기화하십시오. 초기화한 후에는 클라이언트를 여러 요청에서 사용할 수 있습니다. 다음 섹션의 예제를 참조하십시오.

import (
    "github.com/amplitude/analytics-go/amplitude"
)
config := amplitude.NewConfig(AMPLITUDE_API_KEY)
client := amplitude.NewClient(config)

SDK 구성

이름	설명	기본값
`APIKey`	필수입니다. `string`. Amplitude 프로젝트의 API 키입니다. 클라이언트`struct`가 이 프로젝트에 이벤트를 전송합니다. 클라이언트 `struct`를 초기화할 때 이 값을 설정합니다.	`nil`
`FlushQueueSize`	`int`. 이벤트는 버퍼에서 대기하고 배치로 전송됩니다. SDK는 이벤트 수가 `FlushQueueSize`에 도달하면 버퍼를 플러시합니다.	`200`
`FlushInterval`	`time.Duration`. 이벤트는 버퍼에서 대기하고 배치로 전송됩니다. SDK는 `FlushInterval`마다 버퍼를 플러시합니다.	`10 seconds`
`FlushMaxRetries`	`int`. 요청이 오류를 반환할 때 클라이언트가 이벤트를 재시도하는 회입니다.	`12`
`RetryBaseInterval`	`time.Duration`. 요청이 오류를 반환할 때 재시도 간의 기본 간격입니다.	`100 milliseconds`
`RetryThrottledInterval`	`time.Duration`. 스로틀링된 요청에 대한 재시도 간의 기본 간격입니다.	`30 seconds`
`Logger`	로거 인터페이스입니다. Amplitude 클라이언트가 사용하는 로거입니다.	`Go standard Logger`: `log.Logger`.
`ServerZone`	`string`. 프로젝트의 서버 영역입니다. EU와 미국을 지원합니다. EU 데이터 상주국의 경우 EU로 변경하십시오.	`US`
`ServerURL`	`string`. SDK가 이벤트를 전송할 API 엔드포인트 URL입니다. `ServerZone`과 `UseBatch`이 이 URL을 자동으로 선택합니다. 이 필드를 설정하면 SDK는 `ServerZone` 및 `UseBatch`를 무시하고 문자열 값을 사용합니다.	`https://api2.amplitude.com/2/httpapi`
`UseBatch`	`boolean`. 배치 API를 사용할지 여부를 지정합니다. 기본적으로 SDK는 기본 `serverUrl`을 사용합니다.	`false`
`StorageFactory`	`function`. 스토리지 버퍼에 이벤트를 저장하는 스토리지 구조체를 생성합니다. 스토리지 버퍼의 이벤트는 전송을 기다리고 있습니다.	`InMemoryStorage`
`OptOut`	`bool`. 옵트아웃 옵션. `true`로 설정된 경우 클라이언트는 이벤트를 처리하거나 전송하지 않습니다.	`false`
`ConnectionTimeout`	`time.Duration`. API 요청에 대한 시간 제한.	`10 seconds`
`MaxStorageCapacity`	`int`. 스토리지에 있는 보류 중인 이벤트의 최대 개수입니다.	`20000`
`MinIDLength`	`int`. user_id 및 device_id의 최소 길이입니다.	`5`
`ExecuteCallback`	`function`. 클라이언트 수준의 콜백 함수.	`nil`

클라이언트를 초기화하기 전에 구성을 설정하십시오.

일괄 처리 동작 구성

고성능 환경을 지원하기 위해 SDK는 이벤트를 일괄 처리로 전송합니다. SDK는 track 메서드에 의해 기록된 모든 이벤트를 메모리 대기열에 추가하고 백그라운드에서 이벤트를 일괄 처리로 플러시합니다.FlushQueueSize 및 FlushInterval을 사용하여 일괄 처리 동작을 사용자 정의할 수 있습니다. 기본적으로 SDK는 serverUrl가 https://api2.amplitude.com/2/httpapi로 설정된 일반 모드에서 실행됩니다. 한 번에 대량의 데이터를 전송하려면 UseBatch를 true로 설정하여 배치 모드로 전환하십시오. 이 설정은 setServerUrl를 배치 이벤트 업로드 API https://api2.amplitude.com/batch로 설정합니다. 일반 모드와 배치 모드 모두 동일한 플러시 대기열 크기와 플러시 간격을 사용합니다.

package main
import (
    "github.com/amplitude/analytics-go/amplitude"
)
func main() {
    // Create a Config struct
    config := amplitude.NewConfig(AMPLITUDE_API_KEY)
    // Events queued in memory will flush when number of events exceed upload threshold
    // Default value is 200
    config.FlushQueueSize = 100
    // Events queue will flush every certain milliseconds based on setting
    // Default value is 10 seconds
    config.FlushInterval = 5000
    // Pass a Config struct
    // to initialize a Client struct
    // which implements Client interface
    client := amplitude.NewClient(config)
}

이벤트 추적

이벤트는 사용자가 애플리케이션과 상호 작용하는 방식을 나타냅니다. 예를 들어 '버튼 클릭됨'은 기록해야 할 동작을 나타냅니다.

// Track a basic event
// EventOne of UserID and DeviceID is required as well as EventType
client.Track(amplitude.Event{
    UserID:    "user-id",
    EventType: "Button Clicked",
})
// Track events with optional properties
client.Track(amplitude.Event{
    UserID:    "user-id",
    EventType: "Button Clicked",
    EventProperties: map[string]interface{}{
        "name":       "Checkout",
        "a property": "a value",
    },
    EventOptions: amplitude.EventOptions{
        Price: 1.99,
    },
})

사용자 속성

사용자 속성은 사용자가 앱 첫 사용 후 작업을 수행할 때 사용자의 기기 세부 정보, 환경설정, 언어 등을 이해하는 데 도움이 됩니다.

Identify를 사용하면 이벤트를 전송하지 않고도 특정 사용자의 사용자 속성을 설정할 수 있습니다. SDK는 개별 사용자 속성에 대한 , Set, SetOnce, Unset, Add, Append, Prepend, PreInsert, PostInsert, Remove 및 ClearAll 작업을 지원합니다. SDK는 작업을 Identify 구조체 메서드로 선언합니다. 하나의 Identify구조체에 여러 작업을 함께 연결한 다음 해당 구조체를 Amplitude 클라이언트에 전달하여 서버로 전송할 수 있습니다.

이벤트 후에 Identify 호출을 전송하면 작업 결과가 대시보드 사용자의 프로필 영역에 즉시 나타나지만 Identify 호출 후에 다른 이벤트를 전송할 때까지 차트 결과에 나타나지 않습니다. Identify 호출은 앞으로 진행되는 이벤트에만 영향을 줍니다. 자세한 내용은 사용자 속성 및 이벤트를 참조하십시오.

Identify이 구조체는 사용자 속성 설정을 제어할 수 있는 기능을 제공합니다. 먼저 Identify 구조체를 인스턴스화한 다음 Client.Identify() 메서드를 호출합니다.

identifyObj := amplitude.Identify{}
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

Identify.Set

이 메서드는 사용자 속성의 값을 설정합니다. 예를 들어 사용자에 대한 역할 속성을 설정할 수 있습니다.

identifyObj := amplitude.Identify{}
identifyObj.Set("location", "LAX")
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

Identify.SetOnce

이 메서드는 사용자 속성의 값을 한 번만 설정합니다. SetOnce()는 후속 호출을 무시합니다. 예를 들어 사용자의 초기 로그인 방법을 설정할 수 있습니다. SDK는 초기 값만 추적합니다.

identifyObj := amplitude.Identify{}
identifyObj.SetOnce("initial-location", "SFO")
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

Identify.Add

이 메서드는 사용자 속성을 숫자 값으로 증가시킵니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 속성을 0으로 초기화한 후 증가시킵니다. 예를 들어 사용자의 여행 수행 횟수를 추적할 수 있습니다.

identifyObj := amplitude.Identify{}
identifyObj.Add("travel-count", 1)
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

사용자 속성의 배열

배열을 사용자 속성으로 사용할 수 있습니다. 배열을 직접 설정하거나 Prepend(), Append(), PreInsert(), 및 PostInsert()를 사용하여 배열을 생성할 수 있습니다.

Identify.Prepend

이 메서드는 사용자 속성 배열 앞에 값을 추가합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 새 값을 앞에 추가하기 전에 속성을 빈 목록으로 초기화합니다.

identifyObj := amplitude.Identify{}
identifyObj.Prepend("visited-locations", "LAX")
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

식별.추가

이 메서드는 사용자 속성 배열에 하나 이상의 값을 추가합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 새 값을 추가하기 전에 속성을 빈 목록으로 초기화합니다.

identifyObj := amplitude.Identify{}
identifyObj.Append("visited-locations", "SFO")
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

Identify.PreInsert

이 메서드는 사용자 속성에 값이 아직 존재하지 않는 경우 해당 값을 사용자 속성에 미리 삽입합니다. 사전 삽입은 지정된 목록의 시작 부분에 값을 삽입하는 것을 의미합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 새 값을 미리 삽입하기 전에 속성을 빈 목록으로 초기화합니다. 사용자 속성에 기존 값이 있으면 SDK는 아무 작업도 수행하지 않습니다.

identifyObj := amplitude.Identify{}
identifyObj.PreInsert("unique-locations", "LAX")
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

Identify.PostInsert

이 메서드는 사용자 속성에 값이 아직 존재하지 않는 경우 해당 값을 사용자 속성에 사후 삽입합니다. 사후 삽입은 주어진 목록의 끝에 값을 삽입하는 것을 의미합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 새 값을 사후 삽입하기 전에 속성을 빈 목록으로 초기화합니다. 사용자 속성에 기존 값이 있으면 SDK는 아무 작업도 수행하지 않습니다.

identifyObj := amplitude.Identify{}
identifyObj.PostInsert("unique-locations", "SFO")
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

Identify.Remove

이 메서드는 사용자 속성에 값이 있는 경우 사용자 속성에서 해당 값을 제거합니다. 제거는 주어진 목록에서 기존 값을 제거한다는 의미입니다. 해당 항목이 사용자 속성에 존재하지 않는 경우 SDK는 작업을 수행하지 않습니다.

identifyObj := amplitude.Identify{}
identifyObj.Remove("unique-locations", "JFK")
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

사용자 그룹

Amplitude는 사용자를 그룹에 할당하고 해당 그룹에 대해 고유 수행 횟수가와 같은 쿼리를 수행하는 것을 지원합니다. 예를 들어 orgId을 사용하여 사용자를 해당 사용자가 속한 조직별로 그룹화할 수 있습니다. Joe를 orgId 10에, Sue를 orgId 15에 지정할 수 있습니다. Amplitude의 이벤트 세그멘테이션 차트에서 쿼리를 실행할 때, orgId "..수행함"을 선택하여 특정 이벤트를 수행한 조직의 수를 쿼리하십시오. 해당 그룹의 멤버 중 적어도 한 명이 이벤트를 수행한 경우, Amplitude는 해당 그룹을 수행 횟수가에 포함합니다.

그룹을 설정할 때 groupType 및 groupName를 정의하십시오. 이전 예제에서 orgId는 groupType이며, 각 값인 10와 15는 groupName입니다. 또 다른 groupType 예는 sport이며, groupName 값으로 tennis 및 baseball 등이 있습니다. 사용자가 속한 그룹을 지정할 때 SetGroup()를 사용하십시오. SetGroup()는 또한 groupType:groupName를 사용자 속성으로 설정합니다. SetGroup()는 해당 사용자의 groupType에 설정된 기존 groupName값을 덮어쓰며, 이에 대응하는 사용자 속성 값도 덮어씁니다. groupType은 문자열이며, groupName은 사용자가 하나 여러 그룹에 속함을 나타내는 문자열 배열입니다. 예를 들어, Joe가 orgId 10 및 16에 있으면 groupName은 [10, 16]입니다. 코드는 다음과 같을 수 있습니다.

// set group with single group name
client.SetGroup("org-id", []string{"15"}, amplitude.EventOptions{UserID: "user-id"})
// set group with multiple group names
client.SetGroup("org-id", []string{"15", "21"}, amplitude.EventOptions{UserID: "user-id"})

Groups 이벤트 속성을 사용하여 이벤트 수준 그룹을 설정합니다.

// set groups when initial an Event struct
event := amplitude.Event{
    UserID:          "user-id",
    EventType:       "event-type",
    Groups: map[string][]string{"org-id": {"15", "21"}},
  }
// set groups for an existing Event struct
event.Groups["Sport"] = []string{"soccer"}
client.Track(event)

그룹 속성

Group Identify API를 사용하여 특정 그룹의 속성을 설정하거나 업데이트하십시오. 이러한 업데이트는 앞으로 진행되는 이벤트에만 영향을 줍니다.

GroupIdentify() 메서드는 그룹 유형, 그룹 이름 문자열 매개변수 및 Identify 구조체를 받아들여 그룹에 적용합니다.

identifyObj := amplitude.Identify{}
identifyObj.Set("local", "en-us")
client.GroupIdentify("org-id", "15", identifyObj, amplitude.EventOptions{})

매출 추적

사용자의 수익을 추적하는 선호되는 방법은 Revenue()을 수익 인터페이스와 함께 사용하는 것입니다. 수익 struct는 모든 수익 거래를 저장하며, Amplitude의 이벤트 세분화 및 Revenue LTV (Lifetime Value) 차트에서 사용하는 RevenueType 및 ProductID와 같은 몇 가지 특별한 수익 속성을 정의할 수 있도록 해줍니다. 이러한 Revenue 구조체를 Revenue에 전달하여 Amplitude에 수익 이벤트로 전송하십시오. 그러면 Amplitude는 플랫폼에 수익 관련 데이터를 자동으로 표시합니다. 앱 내 구매와 앱 외부 구매를 모두 추적할 수 있습니다.

사용자의 수익을 추적하려면 사용자가 수익을 창출할 때마다 전화하십시오. Revenue()예를 들어 사용자가 한 제품 3대를 3.99달러에 구매했습니다.

revenueObj := amplitude.Revenue{
    Price:       3.99,
    Quantity:    3,
    ProductID:   "com.company.productID",
}
client.Revenue(revenueObj, amplitude.EventOptions{UserID: "user-id"})

수익 인터페이스

이름	유형	설명	기본값
ProductID(선택 사항)	문자열	제품의 식별자입니다. Amplitude는 Google Play 스토어 제품 ID와 같은 것을 권장합니다.	""
수량(옵션)	int	구매한 제품의 수량입니다. `Revenue = Quantity * Price`	0
가격(선택사항 *수익 필드가 설정되어 있지 않은 경우 수익 데이터에 필수)	플로트64	구입한 제품의 가격입니다. 음수 값을 사용하여 환불을 나타낼 수 있습니다. `Revenue = Quantity * Price`	0
수익 유형(선택 사항)	문자열	수익 유형(예: 세금, 환급금, 소득)입니다.	""
영수증(선택 사항)	문자열	수익의 영수증 식별자입니다.	""
ReceiptSig (선택 사항)	문자열	수익의 영수증 서명입니다.	""
속성(선택 사항)	map[string]interface{}	수익 이벤트에 포함시킬 이벤트 속성의 맵입니다.	nil
매출(선택 사항)	플로트64	음수 값을 사용하여 환불을 나타냅니다. `Revenue = Quantity * Price`	0

플러시

이 Flush 메서드는 클라이언트가 버퍼링된 이벤트를 전송하도록 트리거합니다.

client.Flush()

시스템 종료

Shutdown 메서드는 클라이언트 struct를 닫습니다. 닫힌 클라이언트 struct는 새 이벤트를 수락하지 않으며 버퍼의 이벤트를 플러시하려고 시도합니다. 그런 다음 클라이언트struct는 실행 중인 스레드를 종료합니다.

client.Shutdown()

플러그인

플러그인을 사용하면 Amplitude SDK의 동작을 확장할 수 있습니다. 예를 들어 이벤트 속성을 수정하거나(보강 유형), 타사 API로 이벤트를 전송할 수 있습니다(목적지 유형). 플러그인은 Setup() 및 Execute() 메서드를 가진 구조체입니다.

클라이언트 추가

이 Add 메서드는 Amplitude 클라이언트 struct에 플러그인을 추가합니다. 플러그인은 이벤트를 처리하고 전송하는 데 도움이 될 수 있습니다.

client.Add(pluginObj)

클라이언트.제거

Remove 메서드는 지정된 플러그인이 있는 경우 클라이언트struct에서 해당 플러그인을 제거합니다.

client.Remove(pluginName)

플러그인.설정

이 메서드는 플러그인을 사용할 준비를 하는 논리를 포함하고 있으며 Config구조체를 매개변수로 사용합니다. 예상 반환 값은 nil입니다. 이 메서드의 일반적인 용도는 Config에서 설정을 복사하거나 플러그인 종속성을 인스턴스화하는 데 사용됩니다. SDK는 client.Add()를 통해 클라이언트에 플러그인을 등록할 때 이 메서드를 호출합니다.

Plugin.Execute

이 메서드는 이벤트를 처리하기 위한 논리를 포함하고 있으며 *Event 매개변수로 사용합니다. 플러그인을 보강 유형 플러그인으로 사용하는 경우 예상 반환 값은 수정되거나 보강된 이벤트입니다. 플러그인을 대상 유형 플러그인으로 사용하는 경우 예상되는 반환 값은 event(BaseEvent), code(숫자) 및 message(문자열)의 키가 있는 맵입니다. SDK는 Identify, GroupIdentify 및 Revenue 이벤트를 비롯하여 클라이언트 인터페이스를 사용하여 계측된 각 이벤트에 대해 이 메서드를 호출합니다.

플러그인 예제

보강 유형 플러그인

다음은 이벤트의 EventID속성에 증분 정수를 추가하여 계측된 각 이벤트를 수정하는 플러그인의 예입니다.

package main
import "github.com/amplitude/analytics-go/amplitude"
type addEventIDPlugin struct {
    currentID int
    config    amplitude.Config
}
func (plugin *addEventIDPlugin) Name() string {
    return "AddEventId"
}
func (plugin *addEventIDPlugin) Setup(config amplitude.Config) {
    plugin.config = config
}
func (plugin *addEventIDPlugin) Type() amplitude.PluginType {
    return amplitude.PluginTypeEnrichment
}
func (plugin *addEventIDPlugin) Execute(event *amplitude.Event) *amplitude.Event {
    event.EventID = plugin.currentID
    plugin.currentID += 1
    return event
}
func main() {
    config := amplitude.NewConfig(AMPLITUDE_API_KEY)
    client := amplitude.NewClient(config)
    defer client.Shutdown()
    client.Add(&addEventIDPlugin{})
}

목적지 유형 플러그인

다음은 각 계측된 이벤트를 대상 서버 URL로 전송하는 플러그인의 예입니다.

package main
import (
    "bytes"
    "encoding/json"
    "net/http"
    "github.com/amplitude/analytics-go/amplitude"
)
type myDestinationPlugin struct {
    url        string
    config     amplitude.Config
    httpClient http.Client
}
func (plugin *myDestinationPlugin) Name() string {
    return "MyDestinationPlugin"
}
// Setup is called on plugin installation
func (plugin *myDestinationPlugin) Setup(config amplitude.Config) {
    plugin.config = config
    plugin.httpClient = http.Client{}
}
// Type defines your amplitude.PluginType from:
//  - amplitude.PluginTypeBefore
//  - amplitude.PluginTypeEnrichment
//  - amplitude.PluginTypeDestination
func (plugin *myDestinationPlugin) Type() amplitude.PluginType {
    return amplitude.PluginTypeDestination
}
// Execute is called on each event instrumented
func (plugin *myDestinationPlugin) Execute(event *amplitude.Event) {
    payload := map[string]interface{}{"key": "secret", "events": event}
    payloadBytes, err := json.Marshal(payload)
    if err != nil {
        plugin.config.Logger.Errorf("Event encoding failed: ", err)
    }
    request, err := http.NewRequest("POST", plugin.url, bytes.NewReader(payloadBytes))
    if err != nil {
        plugin.config.Logger.Errorf("Building new request failed", err)
    }
    response, err := plugin.httpClient.Do(request)
    if err != nil {
        plugin.config.Logger.Errorf("HTTP request failed", err)
    } else {
        defer response.Body.Close()
    }
}
func main() {
    config := amplitude.NewConfig(AMPLITUDE_API_KEY)
    client := amplitude.NewClient(config)
    defer client.Shutdown()
    client.Add(&myDestinationPlugin{
        // Change it to your target server URL
        url: "https://custom.domain.com",
    })
    client.Track(amplitude.Event{
        UserID: "user-id",
        EventType: "Button Clicked",
    })
}

이전 예제에서는 JSON 형식의 본문과 함께 HTTP POST 요청을 전송합니다.

json

{
  "events": {
    "event_type": "Button Clicked",
    "user_id": "user-id",
    "time": 1660683660056,
    "insert_id": "1c8aac41-8257-4bea-ab3f-de914e39df5e",
    "library": "amplitude-go/0.0.2",
    "plan": {}
  },
  "key": "secret"
}

이 내용이 도움이 되었나요?