> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Log SDK for Game Engine API 레퍼런스

게임 엔진용 GS2-Log SDK의 모델 사양과 API 레퍼런스



## 모델

### EzInGameLog

인게임 로그<br>

게임 클라이언트 또는 서버 사이드 스크립트에서 전송되는 커스텀 로그 엔트리입니다. GS2 API 호출로 자동 생성되는 액세스 로그와 달리, 인게임 로그는 게임 개발자가 플레이어의 행동, 게임 상태 변화, 비즈니스 메트릭 등 게임 고유의 이벤트를 기록하기 위해 명시적으로 전송합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| timestamp | long |  | ✓ |  |  | 일시<br>인게임 로그가 전송된 일시입니다. |
| userId | string |  |  |  |  ~ 128자 | 사용자ID |
| tags | [List&lt;EzInGameLogTag&gt;](#ezingamelogtag) |  |  | [] | 0 ~ 20 items | 태그<br>필터링과 분류를 위해 로그 엔트리에 부여된 키-값 쌍입니다. 태그를 통해 인게임 로그의 효율적인 검색과 집계가 가능합니다(예: 이벤트 타입, 스테이지 ID, 아이템 카테고리). |
| payload | string |  | ✓ |  |  ~ 10485760자 | 페이로드<br>JSON 형식의 커스텀 로그 데이터입니다. 플레이어의 행동, 게임 상태, 비즈니스 메트릭 등 게임 고유의 임의의 정보를 포함할 수 있습니다. 최대 10MB까지 가능합니다. |

**관련 메서드:**
sendInGameLog - 게임 내 로그를 전송합니다


---

### EzInGameLogTag

게임 내 로그의 태그<br>

인게임 로그 항목의 필터링과 분류에 사용되는 키-값 쌍입니다. 각 태그 키는 하나의 로그 항목 내에서 고유해야 합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| key | string |  | ✓ |  |  ~ 64자 | 태그 이름<br>이 태그의 키 이름입니다. 인게임 로그를 검색할 때 필터 조건으로 사용됩니다. |
| value | string |  | ✓ |  |  ~ 128자 | 태그 값<br>이 태그의 값입니다. 키와 조합하여 특정 조건으로 로그를 필터링할 수 있습니다(예: key="stageId", value="stage-001"). |

**관련 메서드:**
sendInGameLog - 게임 내 로그를 전송합니다


**관련 모델:**
EzInGameLog - 인게임 로그



---

## 메서드

### sendInGameLog

게임 내 로그를 전송합니다

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| tags | [List&lt;EzInGameLogTag&gt;](#ezingamelogtag) |  | | [] | 0 ~ 20 items | 태그<br>필터링과 분류를 위해 로그 엔트리에 부여된 키-값 쌍입니다. 태그를 통해 인게임 로그의 효율적인 검색과 집계가 가능합니다(예: 이벤트 타입, 스테이지 ID, 아이템 카테고리). |
| payload | string |  | ✓|  |  ~ 10485760자 | 페이로드<br>JSON 형식의 커스텀 로그 데이터입니다. 플레이어의 행동, 게임 상태, 비즈니스 메트릭 등 게임 고유의 임의의 정보를 포함할 수 있습니다. 최대 10MB까지 가능합니다. |
| gameSession | GameSession | | |  |  | GameSession |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzInGameLog](#ezingamelog) | 게임 내 로그|

#### 구현 예제




**Unity (UniTask)**
```csharp
    var domain = gs2.Log.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.SendInGameLogAsync(
        payload: "{\"category\": \"use-item\", \"count\": 1, \"itemId\": \"item-0001\"}",
        tags: new List<Gs2.Unity.Gs2Log.Model.EzInGameLogTag> {
            new Gs2.Unity.Gs2Log.Model.EzInGameLogTag() {
                Key = "tag1",
                Value = "value1",
            },
            new Gs2.Unity.Gs2Log.Model.EzInGameLogTag() {
                Key = "tag2",
                Value = "value2",
            },
        }
    );
    var item = await result.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Log.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.SendInGameLogFuture(
        payload: "{\"category\": \"use-item\", \"count\": 1, \"itemId\": \"item-0001\"}",
        tags: new List<Gs2.Unity.Gs2Log.Model.EzInGameLogTag> {
            new Gs2.Unity.Gs2Log.Model.EzInGameLogTag() {
                Key = "tag1",
                Value = "value1",
            },
            new Gs2.Unity.Gs2Log.Model.EzInGameLogTag() {
                Key = "tag2",
                Value = "value2",
            },
        }
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Log->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->SendInGameLog(
        "{\"category\": \"use-item\", \"count\": 1, \"itemId\": \"item-0001\"}", // payload
        []
        {
            auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Log::Model::FEzInGameLogTag>>>();
            v->Add(
                MakeShared<Gs2::UE5::Log::Model::FEzInGameLogTag>()
                ->WithKey(TOptional<FString>("tag1"))
                ->WithValue(TOptional<FString>("value1"))
            );
            v->Add(
                MakeShared<Gs2::UE5::Log::Model::FEzInGameLogTag>()
                ->WithKey(TOptional<FString>("tag2"))
                ->WithValue(TOptional<FString>("value2"))
            );
            return v;
        }() // tags
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // 변경된 값 / 결과 값을 취득
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

```


---