콘텐츠로 이동
FirstLook 문서
Get Started

FirstLook SDK 설정

FirstLook SDK는 Unreal Engine 플러그인으로, Unreal 게임에서 FirstLook과 연동할 수 있게 합니다. 플러그인은 Steam 로그인, 인게임 설문, 세션 추적, 커스텀 이벤트, 커스텀 기간 이벤트를 지원합니다. FirstLook SDK의 주요 진입점은 UFirstLookSubsystem이며, FirstLook과 상호작용하는 여러 메서드와 델리게이트를 제공합니다.

이 설정 가이드에서는 Unreal 프로젝트 이름이 MyGame이라고 가정합니다.

Unreal 서브시스템 자세히 알아보기 Unreal 문서

사전 요구 사항

섹션 제목: “사전 요구 사항”

  1. 관리자 대시보드에서 FirstLookSDK를 받습니다. Download SDK

  2. Unreal SDK 설정을 생성합니다. SDK Config
  3. FirstLook에서 Steam 게임을 설정합니다. Steam 연동을 참고하세요.

  4. Steam 계정이 연결된 테스트 플레이어를 플레이테스트에 초대합니다. 플레이어 초대를 참고하세요.

Unreal에 FirstLookSDK 플러그인 설치

섹션 제목: “Unreal에 FirstLookSDK 플러그인 설치”

FirstLookSDK를 받고 게임을 FirstLook에 설정했으니, Unreal 프로젝트에 플러그인을 설치할 수 있습니다.

  1. FirstLookSDK 플러그인을 MyGame/Plugins/FirstLookSDK로 옮깁니다. MyGame/Plugins 폴더가 없으면 만듭니다.

  2. MyGame.uproject 파일에 FirstLookSDK 플러그인을 등록합니다.

    "Plugins": [
      {
        "Name": "FirstLookSDK",
        "Enabled": true
      }
    ]

  3. MyGame.Build.cs 파일에 FirstLookSDK 플러그인을 의존성으로 추가합니다.

    PrivateDependencyModuleNames.AddRange(new string[] {"FirstLookSDK"});

  4. Unreal 에디터에서 FirstLookApiURL과 FirstLookClientURL을 위해 FirstLookSDK 플러그인 설정을 구성합니다:

    Edit > ProjectSettings > Plugins > FirstLook Plugin Settings

    • 또는 DefaultGame.ini에서 플러그인을 구성할 수 있습니다:

      [/Script/FirstLookSDK.FirstLookSDKSettings]
      FirstLookApiURL="https://api.firstlook.gg"
      FirstLookClientURL="https://<game-slug>.firstlook.gg"

      (<game-slug>를 FirstLook 게임 슬러그로 바꿉니다)

    클라이언트 URL은 FirstLook 설정의 도메인에서 확인합니다: Client URL

  5. DefaultEngine.ini에서 OnlineSubsystemSteam을 구성합니다.

    [OnlineSubsystem]
    DefaultPlatformService=Steam
    

    [OnlineSubsystemSteam]
    bEnabled=true
    SteamDevAppId=<steam-app-id>

    (<steam-app-id>를 Steam 앱 ID로 바꿉니다)

  6. Unreal CommonUI를 설정합니다.

    • 이 가이드의 1단계를 따라 기본 Game Viewport Client Class를 CommonGameViewportClient로 설정합니다.

FirstLook Steam 로그인 테스트

섹션 제목: “FirstLook Steam 로그인 테스트”

FirstLookSDK Unreal 플러그인 설정이 끝나면 FirstLook Steam 로그인은 서브시스템 초기화 시 자동으로 호출되어 바로 동작합니다. 로컬에서 연동을 테스트하려면 몇 가지 단계가 더 필요합니다.

  1. Unreal 에디터에서 스탠드얼론 게임 모드용 로깅을 켭니다

    • Edit > Editor Preferences에서 다음으로 이동합니다:

      Level Editor > Play > Play in Standalone Game > Additional Launch Parameters

    • 실행 매개변수에 -log를 추가합니다

      • Standalone Logging

  2. Play as Standalone Game으로 실행합니다

  3. 출력 로그에 LogFirstLookSDK 카테고리에서 로그인 성공을 나타내는 로그가 보여야 합니다

    • 예: LogFirstLookSDK: Verbose: Login succeeded.

세션 추적 Labs

섹션 제목: “세션 추적 ”

FirstLook SDK는 추가 코드 없이 플레이어 세션을 자동으로 추적합니다. 세션은 UFirstLookSubsystem이 초기화될 때 시작되고, 게임 클라이언트가 정상적으로 종료될 때 끝납니다. 아직 FirstLook 계정을 만들지 않은 플레이어도 추적되며, Steam에 로그인한 경우 Steam 계정과 연결된 미연결 플레이어로 대시보드에 표시됩니다.

세션이 기록되기 시작하면 분석 페이지의 Retention 탭과 각 플레이어 프로필에서 플레이어 활동과 세션 길이 데이터를 볼 수 있습니다.

커스텀 이벤트 Labs

섹션 제목: “커스텀 이벤트 ”

자동 세션 추적 외에, 스튜디오에 중요한 게임플레이 이벤트를 직접 계측할 수 있습니다 — 영웅 선택, 매치 결과, 상점 구매 등. UFirstLookSubsystem의 PostCounterEvent 메서드로 이름이 붙은 카운터와 정수 값을 보냅니다:

UCLASS()
class FIRSTLOOKSDK_API UFirstLookSubsystem : public ULocalPlayerSubsystem
{
public:
    // ...
    UFUNCTION(BlueprintCallable, Category = FirstLook)
    void PostCounterEvent(FString CounterName, int32 Count);
    // ...
}

예시

섹션 제목: “예시”

아래는 UCommonActivatableWidget에서 카운터 이벤트를 보내는 예입니다. 로드아웃 화면에서 플레이어가 영웅을 선택했음을 기록합니다:

void UMainMenu::HandleSendCounterEventClicked()
{
    if (ULocalPlayer* OwningLocalPlayer = GetOwningLocalPlayer();
        OwningLocalPlayer != nullptr)
    {
        if (UFirstLookSubsystem* FirstLookSubsystem =
            OwningLocalPlayer->GetSubsystem<UFirstLookSubsystem>())
        {
            FirstLookSubsystem->PostCounterEvent("loadout.hero-a-selected", 1);
        }
    }
}

이벤트 이름과 그룹화

섹션 제목: “이벤트 이름과 그룹화”

이벤트 이름은 <category>.<event-type> 규칙을 따릅니다. 이 패턴을 쓰면 FirstLook이 분석 페이지와 플레이어 프로필에서 관련 이벤트를 자동으로 묶어 카테고리별로 지표를 살펴보기 쉽습니다.

이벤트가 발생하는 위치를 반영하는 카테고리 네임스페이스를 고르세요 — 예: match, lobby, menu, store, in-game. 필요한 만큼 카테고리를 정의할 수 있습니다.

커스텀 기간 이벤트 Labs

섹션 제목: “커스텀 기간 이벤트 ”

카운터 이벤트는 “무슨 일이 있었는지”만 기록하고, 얼마나 오래 걸렸는지가 필요할 때는 기간 이벤트를 씁니다. 매치, 로딩 화면, 메뉴 체류 시간 등 추적하고 싶은 구간의 경과 시간을 잴 수 있습니다.

SDK는 UFirstLookSubsystem에 StartDurationEvent / EndDurationEvent 쌍을 제공합니다:

UCLASS()
class FIRSTLOOKSDK_API UFirstLookSubsystem : public ULocalPlayerSubsystem
{
public:
    // ...
    UFUNCTION(BlueprintCallable, Category = FirstLook)
    void StartDurationEvent(FString DurationName);


    UFUNCTION(BlueprintCallable, Category = FirstLook)
    void EndDurationEvent(FString DurationName);
    // ...
}

활동이 시작될 때 StartDurationEvent, 끝날 때 EndDurationEvent를 호출합니다. 타이밍과 전송은 SDK가 처리하고, 이름만 넘기면 됩니다.

예시

섹션 제목: “예시”

플레이어가 매치에 머문 시간을 추적하는 예입니다. 매치 시작 시 StartDurationEvent, 종료 시 EndDurationEvent를 호출합니다:

void AMyGameMode::OnMatchStart()
{
    for (APlayerController* PC : GetWorld()->GetPlayerControllerIterator())
    {
        if (ULocalPlayer* LP = PC->GetLocalPlayer())
        {
            if (UFirstLookSubsystem* FirstLook = LP->GetSubsystem<UFirstLookSubsystem>())
            {
                FirstLook->StartDurationEvent("match.round");
            }
        }
    }
}


void AMyGameMode::OnMatchEnd()
{
    for (APlayerController* PC : GetWorld()->GetPlayerControllerIterator())
    {
        if (ULocalPlayer* LP = PC->GetLocalPlayer())
        {
            if (UFirstLookSubsystem* FirstLook = LP->GetSubsystem<UFirstLookSubsystem>())
            {
                FirstLook->EndDurationEvent("match.round");
            }
        }
    }
}

이름과 그룹화

섹션 제목: “이름과 그룹화”

기간 이벤트 이름도 카운터 이벤트와 동일한 <category>.<event-type> 규칙을 따릅니다. FirstLook이 분석 페이지에서 카테고리 접두사별로 자동 그룹화합니다.

인게임 설문 테스트

섹션 제목: “인게임 설문 테스트”

FirstLook에 성공적으로 로그인할 수 있으면 FirstLook 서브시스템으로 인게임 설문을 트리거할 수 있습니다.

인게임 설문 인게임 설문 연동 자세히 보기

  1. 게임 클라이언트 배포가 켜진 설문을 만듭니다. 설문 만들기 참고

  2. 새 설문에 대한 트리거를 설정합니다. 트리거 설정 참고.

  3. Unreal에서 설문 델리게이트를 등록합니다:

    UFirstLookSubsystem::OnNewNativeSurveyAvailable:

    • 이 델리게이트가 호출되면 WBP_Survey_Screen 위젯을 표시해야 합니다. 위젯 경로: MyGame/Plugins/FirstLookSDK/Content/UI_Survey/Widgets/WBP_Survey_Screen.uasset

    UFirstLookSubsystem::OnNewBrowserSurveyAvailable:

    • 기본적으로 UFirstLookSubsystem::ActivateSurveyBrowserOverlay로 Steam 브라우저 오버레이를 표시하도록 연결되어 있습니다

  4. 설문용으로 만든 트리거로 UFirstLookSubsystem::PostEvent를 호출합니다. 트리거 조건이 충족되면 이전 단계에서 설정한 델리게이트 중 하나가, 구성된 설문 배포 채널에 따라 호출됩니다.