모듈 설치 및 초기화

애널리틱스 기능을 사용하려면 Hive Axyl SDK에 애널리틱스 모듈을 설치하고 초기화해야 합니다. 아직 Hive Axyl SDK를 설치하지 않았다면 먼저 Hive Axyl SDK를 설치하세요.

애널리틱스 모듈 설치

애널리틱스 모듈은 공통 모듈만 있으면 동작합니다. 이벤트 로그는 로그인하기 전에도 전송하므로 인증 모듈이 없어도 됩니다. 로그인 기능도 사용한다면 직접 코드로 구현하기에서 설치한 인증 모듈을 함께 사용합니다.

공통 모듈 선택

아래 공통 모듈을 선택합니다.

• com.com2usplatform.hiveaxyl.core: Hive Axyl SDK 초기화와 다른 모듈이 공통으로 사용하는 기본 기능

애널리틱스 기능을 위한 모듈 선택

애널리틱스 기능에는 아래 모듈이 추가로 필요합니다.

• com.com2usplatform.hiveaxyl.analytics: 앱에서 발생한 이벤트를 로그 이벤트로 만들고, 여러 로그 이벤트를 요청 한 번에 모아 보내는 이벤트 로그 전송 기능

모듈 설치

애널리틱스 모듈은 SDK 설치와 같은 방법으로 설치합니다. Hive Axyl SDK는 Scoped Registry로만 설치하므로, SDK를 설치할 때 등록한 Hive Axyl Scoped Registry에 애널리틱스 모듈을 추가로 선언하세요.

Packages/manifest.json의 dependencies에 com.com2usplatform.hiveaxyl.core와 애널리틱스 모듈인 com.com2usplatform.hiveaxyl.analytics를 추가하세요.

manifest.json

{
  "scopedRegistries": [
    {
      "name": "Hive Axyl",
      "url": "https://package.openupm.com",
      "scopes": [
        "com.com2usplatform.hiveaxyl"
      ]
    }
  ],
  "dependencies": {
    "com.com2usplatform.hiveaxyl.core": "1.0.0",
    "com.com2usplatform.hiveaxyl.analytics": "1.0.0"
  }
}

설치 확인

설치한 SDK와 애널리틱스 모듈의 네임스페이스가 정상 인식되는지 아래 using 문으로 확인합니다.

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Analytics;

Unity Package Manager에서 설치한 모듈이 Installed 상태로 표시되면 설치가 완료된 것입니다.

SDK 초기화

Initialize

애널리틱스 기능을 사용하려면 앱을 시작할 때 Hive Axyl SDK를 한 번 초기화해야 합니다. SDK는 초기화 과정에서 이벤트 로그 전송에 필요한 런타임을 준비합니다.

1. 앱 정보 생성에서 만든 App ID를 확인하세요.
2. App ID로 CoreConfig.CreateBuilder를 실행해 CoreConfig 객체를 만드세요.
3. HiveBootstrap.Initialize로 초기화를 실행하고, builder에서 AddAnalytics()로 애널리틱스 모듈을 등록하세요.
4. 초기화한 뒤 HiveCore.Resolve<IAnalyticsService>()로 애널리틱스 기능을 가져와 사용하세요.

초기화는 앱 실행 중 한 번만 호출합니다. 4단계. SDK 초기화에서 이미 초기화 코드를 작성했다면 새로 호출하지 말고, 기존 Initialize 호출의 builder에 AddAnalytics()만 추가하세요.

호출 파라미터

필드명	타입	필수 여부	설명
config	CoreConfig	Required	App ID를 담은 CoreConfig 객체입니다. CoreConfig.CreateBuilder로 생성합니다.
assemble	Action<IHiveBuilder>	Required	사용할 기능 모듈을 등록하는 빌더 콜백입니다. 애널리틱스 기능을 사용하려면 builder.AddAnalytics()를 포함하세요.

호출 예시

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Analytics;    // AddAnalytics 확장

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

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddAnalytics();   // 애널리틱스 (IAnalyticsService)
    // 로그인 등 다른 기능도 사용한다면 같은 초기화 호출에서 함께 등록합니다.
    // builder.AddAuth();
    // builder.AddToken();
});

등록한 모듈은 이후 HiveCore.Resolve<IAnalyticsService>()로 가져와 사용합니다.

응답 데이터

성공 시 별도 반환 데이터가 없습니다.

응답 예시

Unity

// 성공하면 예외가 발생하지 않습니다.
IAnalyticsService analytics = HiveCore.Resolve<IAnalyticsService>();

응답 상태

초기화와 모듈 등록의 성공 여부는 HiveCore.Resolve<IAnalyticsService>() 호출 결과로 확인합니다. 예외 없이 인스턴스를 반환하면 초기화와 모듈 등록을 모두 완료한 것입니다. Resolve<T>()에서 모듈 등록이 누락됐을 때 발생하는 예외를 포함해 오류 처리의 공통 원칙은 공통 오류 처리를 참조하세요.

아래 경우에는 초기화할 때 예외가 발생합니다. 이 예외는 메서드 호출 결과로 받는 Failure와 달리 초기 설정을 즉시 실패시킵니다.

• ArgumentNullException: config에 null을 넘긴 경우
• InvalidOperationException: 이미 초기화를 완료한 상태에서 초기화 메서드를 다시 호출한 경우
• DllNotFoundException: Windows 빌드에서 SDK가 사용하는 OS 전용 바이너리를 불러오지 못한 경우. 원인과 대응 방법은 아래 Windows 빌드 사전 조건 참조

Windows 빌드 사전 조건

Windows 빌드에서는 SDK가 C# 코드에서 호출하는 OS 전용 바이너리(네이티브 플러그인)를 함께 불러옵니다. 이 파일을 불러오지 못하면 초기화할 때 DllNotFoundException이 발생합니다. 원인은 두 가지입니다.

• 네이티브 플러그인 파일이 빌드 결과물에 포함되지 않은 경우
• 앱을 실행하는 PC에 Microsoft Visual C++ 2015-2022 재배포 가능 패키지(x64)가 설치되지 않은 경우. 이 패키지는 네이티브 플러그인이 동작하는 데 필요한 Microsoft 런타임 라이브러리 모음으로, Windows가 기본 제공하지 않고 Unity도 빌드 결과물에 함께 넣지 않습니다.

따라서 Windows로 출시할 때는 앱 설치 프로그램에 이 재배포 가능 패키지를 포함하거나 최초 실행할 때 사용자에게 설치를 안내하세요. 다운로드 링크는 예외 메시지에도 포함되어 있습니다.

다음 단계

• 담당자 설정