Unity용 6labs SDK
이 섹션에서는 6labs SDK를 Unity 애플리케이션에 통합하는 방법을 설명합니다.
사전 요구 사항
- Unity 2021 LTS 이상이 필요합니다. 이전 버전은 작동할 수 있지만 적극적으로 지원되지는 않습니다.
- Apple 플랫폼 전용 — 개발 머신에 다음 도구가 설치되어 있는지 확인하세요:
- Xcode 26.2 이상
- CocoaPods 1.12.0 이상
- Unity 프로젝트는 다음 최소 배포 대상을 충족해야 합니다:
- iOS — iOS 15 이상
- tvOS — tvOS 15 이상
- Android — API 레벨 23 (Android 6.0 Marshmallow) 이상
1. 모듈 다운로드 및 가져오기
6labs SDK는 Unity 패키지 파일 형태로 제공됩니다.
다음 단계를 따라 Unity 프로젝트에 모듈을 추가합니다:
- 다운로드 6labs Unity SDK 최신 버전
v3.9.0. - 패키지를 Unity 프로젝트로 가져옵니다:
- Unity 에디터에서 Assets > Import Package > Custom Package를 클릭합니다.
- 시스템에서 다운로드한
.unitypackage파일을 선택하세요. - Import를 클릭하여 가져오기를 완료합니다.
2. 게임플레이 관찰 시작
Start() 메서드를 사용하여 게임플레이 관찰을 시작합니다. 아래 예시를 참고하세요.
SixLabsSDK.Instance.Start( inGameId: "<optional_player_in_game_id>",
developerPayload: "<optional_developer_payload_here>",
callbackOnComplete: (sdkResponse, errorMessage) => {
// sdkResponse == SdkResponse.SUCCESS이면 Start()가 성공적으로 완료된 것입니다
// 결과 처리
// SixLabsSDK.Instance.CurrentState로 SDK의 현재 상태를 확인할 수 있습니다
} );
필요 조건: SDK_STATE_IDLE. 세션이 이미 일시 중지된 상태에서 Start()를 호출하면 ERROR_STATE_NOT_IDLE이 반환됩니다 — 이 경우 세션을 이어가려면 대신 Resume()을 호출하세요. 전체 상태 및 응답 코드 목록은 SDK 상태 및 응답 코드를 참고하세요.
중요 안내
inGameId가 전달되지 않으면 관찰된 세션이 폐기될 수 있으며 AI 분석에 사용되지 않습니다. 이 값이 없으면 세션을 플레이어에게 귀속시킬 수 없으며, 이는 후속 인사이트 생성에 필요합니다.- 게임플레이 관찰을 시작하기 전에 반드시 사용자 동의를 확보해야 합니다. SDK는 자동으로 권한을 요청하지 않으므로, 동의 처리는 게임 로직에서 직접 구현해야 합니다.
- 권장되는 모범 사례로, 게임의 EULA(최종 사용자 라이선스 계약) 또는 개인정보 처리방침에 게임플레이 관찰에 대한 내용을 명시하는 것이 좋습니다.
- 대상 플랫폼에 맞게 앱에 필요한 인터넷 접근 권한이 활성화되어 있는지 확인하세요.
- SDK는 Unity Editor 환경에서는 동작하지 않습니다.
올바르게 테스트하려면 플랫폼별 빌드를 생성한 후 실제
디바이스에서 실행해야 합니다. 에디터에서는
Start()가 대신ERROR_NOT_SUPPORTED와 함께callbackOnComplete를 호출합니다.
참고
다음은
Start() 메서드에 대한 참조 정보입니다.
메서드 시그니처
파라미터
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
inGameId |
string |
아니요 | 선택적이지만 권장되는 사용자 식별자입니다. 생략하면 세션이 폐기될 수 있으며 AI 분석에 사용되지 않습니다. |
developerPayload
|
string |
아니요 | 세션과 연관된 선택적 개발자 정의 메타데이터입니다. 이 값은 세션 요청과 함께 원본 그대로 전달되며, 사용자 정의 추적 정보나 컨텍스트 정보를 첨부하는 데 사용할 수 있습니다. 더 풍부한 developerPayload를 제공하면 AI 기반 분석 및 세션 이해의 품질을 크게 향상시킬 수 있습니다. 자세한 사용 사례와 JSON 예시는 개발자 페이로드 예시 페이지를 참고하세요.예시:
|
callbackOnComplete |
Action<SdkResponse, string> |
아니요 | 호출이 성공하든 실패하든 완료되는 즉시 호출됩니다. 아래 콜백 항목을 참고하세요. |
콜백
이 콜백은 비동기로 호출되며, SdkResponse와 errorMessage를 반환합니다. errorMessage는 성공 시 빈 문자열이며, 실패 시 그 이유를 설명합니다.
| 응답값 | 설명 |
|---|---|
SUCCESS |
세션이 성공적으로 시작되었습니다. |
ERROR_STATE_NOT_IDLE |
SDK가 SDK_STATE_IDLE 상태가 아니었습니다 — 이미 세션이 실행 중이거나 일시 중지되었거나, 이전 세션이 아직 종료 중인 경우입니다. |
ERROR_NOT_SUPPORTED |
현재 플랫폼에서는 게임플레이 관찰 자체가 전혀 지원되지 않습니다 — 현재는 Unity Editor만 해당합니다. |
ERROR_SESSION_FAILED |
요청은 수락되었지만 관찰 세션을 시작하지 못했고, SDK는 SDK_STATE_IDLE 상태로 돌아갔습니다. 이는 세션 생성 실패, 디바이스 성능 제한, 오래된 SDK 버전, 네트워크 문제, 또는 기타 초기화 오류로 인해 발생할 수 있습니다. |
참고
- 전체 상태 및 응답 코드 목록은 SDK 상태 및 응답 코드를 참고하세요.
3. 인게임 ID 설정
SetInGameId() 메서드를 사용하여 플레이어의 인게임 ID를 기존 관찰 세션에 연결합니다. 이 메서드는 사용자 계정이 생성되기 전에 SDK가 초기화된 경우, 로그인한 사용자를 이미 진행 중인 세션에 연결할 때 주로 사용됩니다.
참고
Start()호출 시inGameId를 전달한 경우,SetInGameId()를 호출하면 현재 세션에 설정된 기존 값이 덮어씌워집니다.
참고
다음은
SetInGameId() 메서드에 대한 참조 정보입니다.
메서드 시그니처
파라미터
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
inGameId |
string |
예 | 현재 세션에 연결할 플레이어의 인게임 식별자입니다. |
4. 게임 이벤트 전송
SendGameEvent() 메서드를 사용하여 진행 중인 관찰 세션에서 사용자 지정 게임플레이 이벤트를 기록할 수 있습니다. 이벤트는 세션에 첨부되며, 분석 시 특정 게임플레이 순간과 연관 짓는 데 사용할 수 있습니다.
eventDataJson: "<event_data_as_json>" );
참고
다음은
SendGameEvent() 메서드에 대한 참조 정보입니다.
메서드 시그니처
파라미터
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
eventName |
string |
예 | 기록할 사용자 지정 이벤트의 이름입니다. |
eventDataJson |
string |
예 | 이벤트와 관련된 추가 데이터를 담은 JSON 인코딩 문자열입니다. |
반환 값
| 값 | 설명 |
|---|---|
true |
이벤트가 수락되어 업로드 대기열에 추가되었습니다. |
false |
이벤트가 거부되었습니다. 예를 들어 eventName이 비어 있는 경우입니다. |
5. 고급 제어
Start()는 새 세션에 대한 게임플레이 관찰을 시작합니다. 이후 필요에 따라
Pause(),
Resume(),
Stop()을 사용하여 해당 세션을 제어할 수 있습니다.
5.1 일시 중지 (Pause)
Pause() 메서드를 사용하여 게임플레이 관찰을 일시 중지합니다.
필요 조건: SDK_STATE_CAPTURING. 전체 상태 및 응답 코드 목록은 SDK 상태 및 응답 코드를 참고하세요.
중요 안내
- 게임플레이 관찰을 일시 중지합니다.
- 관찰을 재개하려면 이후에 다시
Resume()을 호출할 수 있습니다.
참고
다음은
Pause() 메서드에 대한 참조 정보입니다.
메서드 시그니처
반환 값
| 값 | 설명 |
|---|---|
SUCCESS |
호출이 수락되어 처리되었습니다. |
ERROR_STATE_NOT_CAPTURING |
SDK가 SDK_STATE_CAPTURING 상태가 아닐 때 반환됩니다 — 예를 들어 게임플레이 관찰이 진행 중이지 않거나, 세션이 이미 일시 중지되었거나, 이미 정지가 진행 중인 경우입니다. 전체 상태 및 응답 코드 목록은 SDK 상태 및 응답 코드를 참고하세요. |
5.2 재개 (Resume)
이전에 Pause()로 일시 중지된 세션을 이어가려면 Resume() 메서드를 사용합니다.
// sdkResponse == SdkResponse.SUCCESS이면 Resume()이 성공적으로 완료된 것입니다
// 결과 처리
// SixLabsSDK.Instance.CurrentState로 SDK의 현재 상태를 확인할 수 있습니다
} );
필요 조건: SDK_STATE_PAUSED. 전체 상태 및 응답 코드 목록은 SDK 상태 및 응답 코드를 참고하세요.
참고
다음은
Resume() 메서드에 대한 참조 정보입니다.
메서드 시그니처
파라미터
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
callbackOnComplete |
Action<SdkResponse, string> |
아니요 | 호출이 성공하든 실패하든 완료되는 즉시 호출됩니다. 아래 콜백 항목을 참고하세요. |
콜백
이 콜백은 비동기로 호출되며, SdkResponse와 errorMessage를 반환합니다. errorMessage는 성공 시 빈 문자열이며, 실패 시 그 이유를 설명합니다.
| 응답값 | 설명 |
|---|---|
SUCCESS |
세션이 성공적으로 재개되었습니다. |
ERROR_STATE_NOT_PAUSED |
SDK가 SDK_STATE_PAUSED 상태가 아니었습니다 — 이어갈 일시 중지된 세션이 없는 경우입니다. |
ERROR_SESSION_FAILED |
요청은 수락되었지만 일시 중지된 세션을 재개하지 못했고, SDK는 SDK_STATE_IDLE 상태로 돌아갔습니다. 이는 세션 또는 런타임 오류, 네트워크 문제, 또는 세션 재개를 방해하는 기타 오류로 인해 발생할 수 있습니다. |
참고
- 전체 상태 및 응답 코드 목록은 SDK 상태 및 응답 코드를 참고하세요.
5.3 정지 (Stop)
Stop() 메서드를 사용하여 현재 세션을 완전히 종료합니다. Pause()와 달리, 정지된 세션은 Resume()으로 이어갈 수 없습니다 — 새 세션을 시작하려면 다시 Start()를 호출해야 합니다.
// sdkResponse == SdkResponse.SUCCESS이면 Stop()이 성공적으로 완료된 것입니다
// 결과 처리
// SixLabsSDK.Instance.CurrentState로 SDK의 현재 상태를 확인할 수 있습니다
} );
필요 조건: SDK_STATE_CAPTURING 또는 SDK_STATE_PAUSED. 전체 상태 및 응답 코드 목록은 SDK 상태 및 응답 코드를 참고하세요.
참고
다음은
Stop() 메서드에 대한 참조 정보입니다.
메서드 시그니처
파라미터
| 파라미터 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
callbackOnComplete |
Action<SdkResponse, string> |
아니요 | 호출이 성공하든 실패하든 완료되는 즉시 호출됩니다. 아래 콜백 항목을 참고하세요. |
콜백
이 콜백은 비동기로 호출되며, SdkResponse와 errorMessage를 반환합니다. errorMessage는 성공 시 빈 문자열이며, 실패 시 그 이유를 설명합니다.
| 응답값 | 설명 |
|---|---|
SUCCESS |
호출이 수락되어 세션이 종료되었습니다. |
ERROR_STATE_NOT_CAPTURING |
SDK가 SDK_STATE_CAPTURING 또는 SDK_STATE_PAUSED 상태가 아니었습니다 — 정지할 활성 세션이나 일시 중지된 세션이 없는 경우입니다. |
참고
- 전체 상태 및 응답 코드 목록은 SDK 상태 및 응답 코드를 참고하세요.
6. SDK 상태 및 응답 코드
SDK의 상태 및 응답 코드는 다음과 같습니다:
SixLabsSDK.Instance.CurrentState를 사용하면 언제든 SDK의 현재 상태를 확인할 수 있습니다.Start(),Pause(),Resume(),Stop()은 유효한 SDK 상태에서만 호출할 수 있습니다. 유효하지 않은 상태에서 작업을 호출하면 오류가 반환됩니다.Pause()는SdkResponse를 직접 반환합니다.Start(),Resume(),Stop()은 선택적인callbackOnComplete콜백을 통해 결과를 반환합니다.callbackOnComplete콜백은 비동기적으로 호출됩니다.
6.1 상태
SDK_STATE_IDLE = 100,
SDK_STATE_CAPTURING = 101,
SDK_STATE_STOPPING = 102,
SDK_STATE_PAUSED = 103
}
| 상태 | 값 | 설명 |
|---|---|---|
SDK_STATE_IDLE |
100 |
게임플레이를 관찰하고 있지 않은 상태입니다. 기본 상태이며, 세션이 종료되거나 시작에 실패하면 이 상태로 돌아갑니다. |
SDK_STATE_CAPTURING |
101 |
게임플레이를 활발히 관찰하고 있는 상태입니다. 활성 세션뿐 아니라 버퍼링, 업로드 등 백그라운드 처리 과정도 포함합니다. |
SDK_STATE_STOPPING |
102 |
세션이 정지되는 중입니다. SDK가 SDK_STATE_IDLE로 돌아가기 전에 남아 있는 처리를 마무리하고 있습니다. |
SDK_STATE_PAUSED |
103 |
세션이 일시 중지된 상태입니다. 게임플레이 관찰은 잠시 중단되었지만 세션은 계속 열려 있으며, 이전에 관찰된 데이터는 계속 업로드될 수 있습니다. |
6.2 응답 코드
SUCCESS = 0,
ERROR_STATE_NOT_IDLE = 1000,
ERROR_STATE_NOT_CAPTURING = 1001,
ERROR_NOT_SUPPORTED = 1002,
ERROR_STATE_NOT_PAUSED = 1003,
ERROR_SESSION_FAILED = 1004
}
| 응답값 | 값 | 설명 |
|---|---|---|
SUCCESS |
0 |
작업이 수락되어 성공적으로 완료되었습니다. Stop()의 경우, 세션이 종료되었다는 의미입니다. |
ERROR_STATE_NOT_IDLE |
1000 |
SDK가 유휴 상태가 아닐 때 Start()가 호출되었습니다. 이미 세션이 실행 중이거나, 일시 중지되었거나, 정지 중일 수 있습니다. |
ERROR_STATE_NOT_CAPTURING |
1001 |
SDK가 관찰 중이지 않을 때 Pause() 또는 Stop()이 호출되었습니다. Stop()은 일시 중지된 세션을 종료할 때도 사용할 수 있습니다. |
ERROR_NOT_SUPPORTED |
1002 |
게임플레이 관찰이 지원되지 않는 플랫폼(예: Unity Editor)에서 Start()가 호출되었습니다. |
ERROR_STATE_NOT_PAUSED |
1003 |
SDK가 일시 중지 상태가 아닐 때 Resume()이 호출되었습니다. SDK가 유휴 상태일 때 새 세션을 시작하려면 Start()를 사용하세요. |
ERROR_SESSION_FAILED |
1004 |
요청은 수락되었지만 관찰을 시작하지 못했고, SDK는 SDK_STATE_IDLE 상태로 돌아갔습니다. 예를 들어 저사양 디바이스, 오래된 SDK 버전, 네트워크 문제, 또는 기타 초기화 문제로 인해 세션 생성이 실패할 수 있습니다. 이 오류는 즉시 거부되는 것이 아니라 callbackOnComplete를 통해 전달됩니다. |