IAnalyticsService

앱 클라이언트에서 발생한 이벤트를 로그로 만들어 Hive Axyl 분석 로그 서버로 전송하는 서비스입니다. 이벤트 이름과 발생 시각에 앱이 정의한 속성을 더해 로그 이벤트를 만들고, 여러 이벤트를 한 번의 요청으로 전송합니다. 서버는 로그 이벤트의 내용을 해석하지 않고 수집합니다.

인터페이스: IAnalyticsService
네임스페이스: Hive.Axyl.Analytics
패키지: com.com2usplatform.hiveaxyl.analytics

등록과 획득

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Analytics;

var config = CoreConfig.CreateBuilder("{appId}").Build();

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddAnalytics();
});

IAnalyticsService analytics = HiveCore.Resolve<IAnalyticsService>();

메서드 요약

'인증' 열의 의미는 인증 요구 표기를 참조하세요.

메서드	인증	설명
CollectClientLogAsync	불필요	로그 이벤트 목록을 Hive Axyl 분석 로그 서버로 전송합니다.

공통 파라미터

모든 메서드의 마지막 파라미터는 ApiCallContext? context = null입니다. 생략하면 기본값이 적용됩니다. 자세한 내용은 호출 컨텍스트를 참조하세요.

모든 메서드는 요청 본문을 request 파라미터로 받으며, request는 Required입니다. 아래 메서드 설명에서는 요청 타입만 표기하고 파라미터 표는 생략합니다. 각 요청 타입의 필드는 데이터 타입에서 확인하세요.

발생 예외

ArgumentNullException: request가 null인 경우

공통 Failure 코드

아래 코드는 서버가 코드로 응답하지만 기능 관점의 결과가 아니므로 Outcome이 아닌 Failure로 분기합니다. 원인 코드는 Failure.Problem.ExternalCode에 담깁니다. 결과 갈래와 분기 방법은 Core 결과 모델을 참조하세요.

bad_request: 잘못된 요청
invalid_parameter: 요청 파라미터 형식 오류
missing_field: 필수 필드나 X-App-Id 같은 필수 헤더 자체의 누락
missing_app_id: X-App-Id 헤더를 보냈지만 값이 빈 경우
unauthorized: 인증 토큰이 없거나 유효하지 않은 경우
token_expired: 인증 토큰 만료
forbidden: 요청 권한 없음
resource_not_found: 요청한 리소스 없음
method_not_allowed: 허용되지 않은 요청 방식
resource_conflict: 요청과 리소스 상태의 충돌
unprocessable_content: 처리할 수 없는 요청 내용
rate_limit_exceeded: 허용 한도를 넘은 요청 빈도
internal_error: 서버 내부 오류
service_unavailable: 서비스 일시 중단

메서드

CollectClientLogAsync

로그 이벤트 목록을 Hive Axyl 분석 로그 서버로 전송합니다. 서버가 로그를 수집하면 Success를 반환하며, 응답으로 받는 데이터는 없습니다. App ID는 SDK가 요청마다 자동으로 전달하므로 요청에 넣지 않습니다.

이 메서드는 로그인하기 전과 로그인한 후 모두 호출합니다. 로그인 전에는 SDK가 인증 토큰 없이 요청을 보냅니다. 로그인 세션이 활성화된 뒤에는 SDK가 세션의 인증 토큰을 요청에 자동으로 실어 보내며, 서버는 이 토큰으로 사용자를 판별합니다.

Unity

Task<AnalyticsCollectClientLogResult> CollectClientLogAsync(ClientLogCollectRequest request, ApiCallContext? context = null);

요청: ClientLogCollectRequest
응답: 없음
인증: 불필요

결과 케이스 — AnalyticsCollectClientLogResult

결과 케이스	와이어 코드	설명
`Success`	—	서버가 로그를 수집했습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

호출 예시

Unity

using System;
using System.Collections.Generic;
using Hive.Axyl.Analytics;
using Hive.Axyl.Core;

var result = await analytics.CollectClientLogAsync(new ClientLogCollectRequest
{
    LogBody = new[]
    {
        new ClientLogEvent
        {
            EventTime = DateTimeOffset.Now,
            EventName = "levelup_log",
            DeviceId  = deviceKey,   // 로그인에 사용하는 DeviceKey와 같은 값
            AdditionalProperties = new Dictionary<string, string>
            {
                ["level"]        = "12",              // 숫자
                ["stage"]        = "\"boss_room\"",   // 문자열은 큰따옴표까지 넣으세요.
                ["isFirstClear"] = "true",            // 불리언
            },
        },
    },
});

if (result is AnalyticsCollectClientLogResult.Failure failure)
{
    HiveError error = failure.Problem;
}

구현 절차는 이벤트 로그 전송을 참조하세요.

데이터 타입

ClientLogCollectRequest

로그 이벤트 전송 요청입니다.

필드	타입	필수 여부	설명
`LogBody`	IReadOnlyList<ClientLogEvent>	Required	전송할 로그 이벤트 목록입니다. 기본값은 빈 목록이며, 비어 있어도 요청은 그대로 전송됩니다.

ClientLogEvent

로그 이벤트 하나입니다. 아래 표에 없는 속성은 앱이 이름을 정해 AdditionalProperties에 원하는 만큼 추가합니다.

필드	타입	필수 여부	설명
`EventTime`	`DateTimeOffset`	Required	이벤트가 발생한 시각입니다. 시차를 포함한 RFC 3339 형식으로 전송됩니다. 지정하지 않으면 `DateTimeOffset`의 기본값이 전송되므로 반드시 지정하세요.
`EventName`	`string`	Required	이벤트 이름입니다. 예: `levelup_log`
`DeviceId`	`string?`	Optional	기기 식별자입니다. 앱이 로그인 요청에 넣는 `DeviceKey`와 똑같은 값을 지정하세요. SDK는 이 값을 자동으로 채우지 않습니다. 값 준비 방법은 DeviceId를 참조하세요.
`UserId`	`string?`	Optional	사용자 식별자입니다.
`IdentifierProvider`	ClientLogEventIdentifierProvider?	Optional	식별자 제공자입니다. 서버가 항상 `hive`로 덮어쓰므로 지정하지 마세요.
`AdditionalProperties`	`IDictionary<string, string>`	Optional	앱이 이름을 정한 이벤트 속성입니다. 키는 속성 이름이고 값은 JSON 값을 나타내는 문자열입니다. 각 속성은 `eventName`과 같은 수준의 필드로 전송됩니다. 기본값은 빈 딕셔너리이며, 비어 있으면 아무 속성도 전송하지 않습니다. 작성 규칙은 AdditionalProperties 작성 규칙을 참조하세요.

AdditionalProperties 작성 규칙

AdditionalProperties의 값에는 화면에 표시할 텍스트가 아니라 JSON 값 자체를 문자열로 넣으세요. SDK는 값을 검증하지 않고 요청 본문에 그대로 기록하므로, 올바른 JSON 값이 아니면 요청 본문 전체가 잘못된 JSON이 됩니다. 값이 null이면 JSON null로 전송됩니다.

값의 종류	C# 코드에 넣는 값	전송되는 JSON
숫자	`"42"`	`42`
문자열	`"\"gold\""`	`"gold"`
불리언	`"true"`	`true`
배열	`"[1,2]"`	`[1,2]`
객체	`"{\"a\":1}"`	`{"a":1}`
JSON null	`"null"`	`null`

eventTime, eventName, deviceId, userId, identifierProvider는 선언된 필드가 전송될 때 쓰는 이름이므로 속성 이름으로 사용하지 마세요. 같은 이름을 쓰면 한 로그 이벤트에 같은 이름의 필드가 두 번 전송될 수 있습니다.

열거형

앱 코드에는 C# 멤버 이름을 입력하세요. 와이어 값은 서버와 주고받는 문자열입니다.

ClientLogEventIdentifierProvider

로그 이벤트의 식별자 제공자입니다. ClientLogEvent.IdentifierProvider에 지정하지만, 서버가 항상 hive로 덮어씁니다.

C# 멤버	와이어 값	설명
`Unspecified`	`CLIENT_LOG_EVENT_IDENTIFIER_PROVIDER_UNSPECIFIED`	값을 지정하지 않은 기본값입니다.
`Hive`	`hive`	Hive 식별자 제공자입니다.