이벤트 파이프라인

아티클
10/05/2023

이벤트 파이프라인은 PlayFab Services SDK의 일부인 기능이며 주요 목적은 게임 개발자가 PlayFab Insights에 저장할 이벤트를 보낼 수 있도록 하는 것입니다. 이를 통해 개발자는 배치 크기, 전송 빈도 및 적절한 원격 분석 솔루션의 기타 측면을 지정할 수 있습니다.

게임 개발자의 부담을 덜어주고 대신 모든 측면을 처리하는 데 도움이 됩니다. 구성 가능한 이벤트 파이프라인에 대한 지원이 있습니다. 타이틀은 이러한 파이프라인을 하나 이상 포함할 수 있으며 각각 고유한 속성으로 구성할 수 있습니다.

파이프라인의 몇 가지 기본 개념을 살펴보겠습니다.

파이프라인 유형

파이프라인 유형은 파이프라인이 내보내는 이벤트 유형과 직접적인 관련이 있습니다. 개발자가 인스턴스화할 수 있는 두 가지 유형의 파이프라인이 있습니다.

원격 분석 이벤트 파이프라인: 원격 분석 이벤트만 내보낼 수 있으며 원격 분석 이벤트 쓰기 REST API를 사용합니다.
PlayStream 이벤트 파이프라인: PlayStream 이벤트만 내보낼 수 있으며 Write Events REST API를 사용합니다.

유형과 구성이 다른 여러 파이프라인이 있을 수 있지만 생성 후에는 파이프라인 유형을 변경할 수 없으며 파이프라인을 다시 인스턴스화해야 합니다.

인증 유형

파이프라인 생성의 또 다른 중요한 부분은 인증 유형입니다. PlayFab 이벤트에 대해 지원되는 두 가지 인증 메커니즘인 엔터티 인증 및 원격 분석 키 인증이 있습니다.

엔터티 인증은 게임 개발자가 추가 집계 또는 분석을 위해 이벤트를 특정 엔터티에 연결하려는 경우에 사용됩니다. 예를 들어 게임 개발자는 세분화를 허용하는 타이틀 플레이어의 추가 행동 분석을 수행하기 위해 플레이어의 행동과 관련된 이벤트를 기록할 수 있습니다.

원격 분석 키 인증은 게임 개발자가 엔터티에 연결할 필요가 없는 이벤트를 기록하려는 경우에 사용됩니다. 예를 들어 플레이어가 로그인하기 전에 타이틀은 추가 분석을 위해 수집하려는 성능 또는 특정 지표와 관련된 이벤트를 보내기 시작할 수 있습니다. 이는 정기적인 엔터티 인증 프로세스를 거치지 않고도 수행할 수 있습니다.

지원되는 인증 유형/이벤트 유형 조합

	엔터티 인증	원격 분석 키 인증
원격 분석 이벤트	유효	유효
PlayStream 이벤트	유효	잘못됨

엔터티 인증

이 인증 유형은 일반적이고 가장 일반적인 PlayFab 인증 방법입니다. 특정 엔터티와 밀접하게 관련되어 있으며 후속 호출에서 사용할 엔터티 토큰을 가져오려면 해당 PlayFab 로그인 API를 호출해야 합니다. 다음 목록은 엔터티 인증과 함께 사용할 수 있는 다양한 엔터티 유형을 나타냅니다.

네임스페이스: 네임스페이스 항목은 스튜디오 내의 모든 타이틀에 대한 모든 글로벌 정보를 나타냅니다.
타이틀: 타이틀 엔터티는 해당 타이틀에 대한 모든 전역 정보를 나타냅니다.
master_player_account: master_player_account는 스튜디오 내의 모든 타이틀이 공유하는 플레이어 엔터티입니다.
title_player_account: 대부분의 개발자에게 title_player_account는 가장 전통적인 방식으로 플레이어를 나타냅니다.
character: 캐릭터 엔터티는 title_player_account의 하위 엔터티입니다.
그룹: 그룹 항목은 다른 항목의 컨테이너입니다. 현재 플레이어와 캐릭터로 제한됩니다.

다양한 항목 유형에 대한 자세한 내용은 기본 제공 항목 유형을 참조하세요.

또한 유효한 PFEntityHandle을 제공하여 파이프라인 생성 후 파이프라인 항목을 업데이트할 수 있습니다. 따라서 게임 개발자는 이벤트를 연결하기 위해 엔터티를 추가하거나(see 엔티티 인증으로 전환 또는 엔터티 업데이트 섹션 참조) 엔터티와 관련되지 않은 항목을 기록하기 위해 엔터티를 제거할 수도 있습니다(see 원격 분석 키 인증으로 전환 섹션 참조).

엔터티가 파이프라인에 있는 경우 항상 원격 분석 키 인증보다 우선합니다.

원격 분석 키 인증

원격 분석 키 인증에는 엔터티 토큰이 필요하지 않으므로 특정 엔터티에 연결되지 않습니다.

원격 분석 키 인증이 사용되는 경우 파이프라인 생성 중에 PFEventPipelineTelemetryKeyConfig 구조체가 필요합니다. 이 구조체에는 두 가지 주요 부분이 있습니다.

PlayFab 게임 관리자를 통해 생성 및 관리되는 문자열로 구성된 원격 분석 키입니다.
이벤트 업로드에 사용해야 하는 올바른 서비스 구성을 SDK에 알리는 PFServiceConfigHandle. 서비스 구성 핸들은 SDK 초기화 중에 PFServiceConfigCreateHandle을 호출하여 생성됩니다.

개발자가 원격 분석 키를 사용하려는 경우 파이프라인이 인스턴스화된 후에 원격 분석 키를 추가할 방법이 없기 때문에 파이프라인 생성 시 제공하는 것이 중요합니다.

원격 분석 키 인증은 원격 분석 이벤트에만 사용할 수 있음을 언급할 가치가 있습니다. PlayStream 이벤트를 지원하지 않습니다.

이벤트 파이프라인 구성

앞서 언급한 것처럼 이벤트 파이프라인에는 PFEventPipelineConfig 구조체 매개 변수를 통해 파이프라인 생성 후 제공할 수 있는 일부 구성 가능한 속성이 있습니다.

구성 가능한 속성은 다음과 같습니다.

maxEventsPerBatch: PlayFab에 쓰기 전에 일괄 처리되는 최대 이벤트 수입니다.
maxWaitTimeInSeconds: 불완전한 배치를 보내기 전에 파이프라인이 대기하는 최대 시간입니다.
pollDelayInMs: 파이프라인이 이벤트 버퍼를 비운 후 다시 읽기 위해 대기하는 시간입니다.
compressionLevel: 압축 알고리즘에 사용되는 압축 수준을 정의합니다. 압축에 대한 자세한 내용은 GZIP 압축를 참조하세요.
retryOnDisconnect: 이벤트 파이프라인은 연결 끊김으로 인해 실패한 이벤트 전송을 다시 시도합니다. 원격 분석 이벤트 파이프라인에만 사용할 수 있습니다.
bufferSize: 파이프라인 버퍼의 이벤트 양 제한입니다.

PFEventPipelineConfig에 일부 속성만 지정된 경우 비어 있는 속성을 덮어쓰고 기본값을 사용합니다.

이벤트 파이프라인에 대해 이러한 속성을 업데이트하는 방법에 대한 예제는 업데이트 파이프라인 구성을 참조하세요.

GZIP 압축

이벤트 파이프라인은 GZIP 압축 표준을 사용하여 본문 페이로드를 압축하는 옵션을 제공합니다.

원하는 압축 수준은 PFEventPipelineUpdateConfiguration API 매개 변수의 일부인 PFEventPipelineConfig 구조 내에서 지정할 수 있습니다.

압축 수준이 낮을수록 압축 속도가 낮아지지만 속도가 가장 높고 압축 수준이 높을수록 압축 속도가 향상되지만 압축 속도가 가장 느립니다. 압축 속도의 차이는 모두 전송되는 데이터 형식에 따라 달라집니다. 데이터의 크기와 임의성에 따라 압축 속도는 다른 수준에서도 동일할 수 있습니다.

트레이드 오프:

압축을 사용하면 압축 알고리즘 실행의 복잡성이 증가하기 때문에 CPU 시간이 증가하지만, 반면에 네트워크 본문 페이로드는 크게 감소합니다. 따라서 게임 요구 사항 및 리소스에 따라 압축을 사용해야 하는 경우 게임 개발자는 이를 충족해야 합니다.

내부 유효성 검사에 따라 CPU 시간이 평균 20% 증가하고 페이로드 본문 크기가 평균 91% 감소합니다. 이러한 백분율은 압축되는 데이터의 페이로드 크기와 복잡성에 따라 크게 달라질 수 있습니다.

이벤트 처리기

파이프라인 생성의 일부로 게임 개발자는 이벤트가 업로드될 때 호출되는 두 가지 선택적 이벤트 처리기를 제공할 수 있습니다.

그러나 게임 개발자가 "시작하고 잊어버리는" 경험을 원하는 경우 이벤트 처리기 제공을 생략할 수 있습니다.

제공할 수 있는 이벤트 처리기는 다음과 같습니다.

PFEventPipelineBatchUploadSucceededEventHandler: 이름에서 알 수 있듯이 PlayFab에 성공적으로 업로드된 모든 이벤트를 수신합니다.
PFEventPipelineBatchUploadFailedEventHandler: 파이프라인 재시도 로직을 통과한 후 모든 실패한 이벤트를 수신합니다.

파이프라인 생성 예시

아래에서 이전에 논의된 주제를 기반으로 이벤트 파이프라인을 인스턴스화하는 방법에 대한 다양한 예를 찾을 수 있습니다.

엔터티 인증을 사용한 원격 분석 이벤트 파이프라인 생성

개발자가 원격 분석 이벤트를 전송하려고 하고 원격 분석 키 인증을 사용할 필요가 없는 경우 PFEventPipelineCreateTelemetryPipelineHandleWithEntity API는 다음 예와 같이 이러한 용도로 사용됩니다.

void EventPipelineCreation(PFEntityHandle entityHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithEntity(
        entityHandle,                       // entityHandle
        taskQueueHandle,                    // queue
        nullptr,                            // eventPipelineBatchUploadedEventHandler
        nullptr,                            // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

이 예제에서는 엔터티 인증을 사용하고 처리기가 없는 원격 분석 이벤트 파이프라인을 생성하는 방법을 보여줍니다. 이것은 파이프라인이 이벤트를 발생시키고 결과를 잊어버린다는 것을 의미합니다.

원격 분석 키 인증을 사용한 원격 분석 이벤트 파이프라인 생성

개발자가 원격 분석 이벤트를 전송하려고 하고 원격 분석 키 인증을 사용해야 하는 경우 PFEventPipelineCreateTelemetryPipelineHandleWithKey API는 다음 예제와 같이 이 목적을 수행합니다.

void EventPipelineCreation(PFServiceConfigHandle serviceConfigHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    PFEventPipelineTelemetryKeyConfig telemetryKeyConfig
    {
        "myTelemetryKey",                   // telemetryKey
        serviceConfigHandle,                // serviceConfigHandle
    };

    HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithKey(
        &telemetryKeyConfig,                // eventPipelineTelemetryKeyConfig
        taskQueueHandle,                    // queue
        nullptr,                            // eventPipelineBatchUploadedEventHandler
        nullptr,                            // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

이 예제에서는 엔터티 인증을 사용하지 않는 원격 분석 이벤트 파이프라인을 생성하는 방법을 보여줍니다.

이벤트 파이프라인은 나중에 엔터티를 추가할 가능성이 있는 원격 분석 키를 사용하여 이벤트 업로드를 시작합니다. 엔터티 인증으로 전환 또는 엔터티 업데이트를 참조하세요.

PlayStream 이벤트 파이프라인 생성

개발자가 PlayStream 이벤트를 보내려는 경우 PFEventPipelineCreatePlayStreamPipelineHandle API는 다음 예제와 같이 이 목적을 수행합니다.

void EventPipelineCreation(PFEntityHandle entityHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    HRESULT hr = PFEventPipelineCreatePlayStreamPipelineHandle(
        entityHandle,                       // entityHandle
        taskQueueHandle,                    // queue
        nullptr,                            // eventPipelineBatchUploadedEventHandler
        nullptr,                            // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

이 예제는 엔터티 인증을 사용하고 처리기가 없는 PlayStream 이벤트 파이프라인이 생성되는 방법을 보여줍니다. 이는 파이프라인이 이벤트를 발생시키고 결과를 잊어버린다는 것을 의미합니다.

이벤트 처리기를 사용하는 이벤트 파이프라인

이 예제는 이벤트 처리기가 파이프라인 생성 API에 제공되는 방법을 보여줍니다.

void CALLBACK OnBatchUploadedHandler(void* context, PFUploadedEvent const* const* events, size_t eventsCount)
{
    // Handle response
}

void CALLBACK OnBatchUploadFailedHandler(void* context, HRESULT hr, const char* errorMessage, PFEvent const* const* events, size_t eventsCount)
{
    // Handle response
}

void EventPipelineCreation(PFEntityHandle entityHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithEntity(
        entityHandle,                       // entityHandle
        taskQueueHandle,                    // queue
        OnBatchUploadedHandler,             // eventPipelineBatchUploadedEventHandler
        OnBatchUploadFailedHandler,         // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

예에서 볼 수 있듯이 OnBatchUploadedHandler 및 OnBatchUploadFailedHandler는 이벤트 파이프라인이 생성될 때 전달되는 두 개의 서로 다른 콜백 함수로 선언됩니다. 이벤트와 관련된 모든 결과는 결과가 성공했는지 실패했는지에 따라 이 두 함수 중 하나에서 반환됩니다. 결과를 처리하는 방법은 게임 개발자에게 달려 있습니다.

이벤트 방출

이벤트 내보내기는 이벤트 파이프라인이 이미 생성된 후에는 간단한 작업입니다. 게임 개발자는 기존 이벤트 파이프라인 핸들과 전송하려는 이벤트를 수신하는 PFEventPipelineEmitEvent API를 호출해야 합니다.

void EmitEvent(PFEventPipelineHandle handle)
{
    PFEvent myEvent
    {
        nullptr,
        "custom.playfab.events.PlayFab.Test.TelemetryEventPipelineTests",
        "TelemetryEvent",
        nullptr,
        "{}"
    };

    HRESULT hr = PFEventPipelineEmitEvent(
        handle,
        &myEvent
    );

    if (FAILED(hr))
    {
        printf("Failed emitting event: 0x%x\r\n", hr);
        return;
    }
}

원격 분석 키 인증을 사용할 때 PFEntityKey의 일부로 entityType에 유효한 값은 "external"뿐입니다. 다른 엔터티 유형은 거부되고 이벤트는 업로드되지 않습니다.

원격 분석 키 인증을 사용할 때 유효한 PFEntityKey의 예:

void EmitEvent(PFEventPipelineHandle handle)
{
    PFEntityKey pfEntityKey{ "my-unique-ID", "external" };  // Note the "external" value

    PFEvent myEvent
    {
        &pfEntityKey,
        "custom.playfab.events.PlayFab.Test.EventsWithTelemetryKey",
        "TelemetryEvent",
        nullptr,
        "{}"
    };

    HRESULT hr = PFEventPipelineEmitEvent(
        handle,
        &myEvent
    );

    if (FAILED(hr))
    {
        printf("Failed emitting event: 0x%x\r\n", hr);
        return;
    }
}

이벤트가 전송될 때 버퍼 크기 제한을 초과하면 SDK에서 다음과 같은 오류가 발생합니다:

E_PF_API_CLIENT_REQUEST_RATE_LIMIT_EXCEEDED (0x892354dd)

필요에 따라 버퍼의 적절한 크기를 설정해야 합니다.

엔터티 인증으로 전환 또는 엔터티 업데이트

원격 분석 키 구성만 사용하여 파이프라인을 생성한 경우 엔터티 인증으로 전환하거나 다른 엔터티를 사용하도록 파이프라인을 업데이트하려는 경우 방법이 있습니다.

PFEventPipelineAddUploadingEntity를 사용하면 항목을 다시 초기화할 필요 없이 실행 중인 파이프라인에 연결할 수 있습니다. 또한 기존 엔터티(있는 경우)를 바꿉니다.

예제:

원격 분석 이벤트 파이프라인은 타이틀 실행 시작 시 원격 분석 키 구성으로 생성됩니다. 이에 대한 가능한 이유는 아직 플레이어 ID가 없거나 단순히 플레이어와 관련된 어떤 것도 기록하고 싶지 않기 때문일 수 있습니다.

void EventPipelineCreation(PFServiceConfigHandle serviceConfigHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    PFEventPipelineTelemetryKeyConfig telemetryKeyConfig
    {
        "myTelemetryKey",                   // telemetryKey
        serviceConfigHandle,                // serviceConfigHandle
    };

    HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithKey(
        &telemetryKeyConfig,                // eventPipelineTelemetryKeyConfig
        taskQueueHandle,                    // queue
        nullptr,                            // eventPipelineBatchUploadedEventHandler
        nullptr,                            // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

그런 다음 플레이어가 로그인했거나 다음과 같이 기존 이벤트 파이프라인 핸들과 원하는 엔터티 핸들로 PFEventPipelineAddUploadingEntity를 호출할 수 있도록 특정 엔터티에 연결된 이벤트 전송을 시작하려고 합니다.

void EventPipelineUpdateEntity(PFEventPipelineHandle handle)
{
    HRESULT hr = PFEventPipelineAddUploadingEntity(
        handle,                 // eventPipelineHandle
        entityHandle            // entityHandle
    );

    if (FAILED(hr))
    {
        printf("Failed adding uploading entity: 0x%x\r\n", hr);
        return;
    }
}

이 호출 후 파이프라인은 해당 엔터티에 연결된 모든 후속 이벤트를 기록하기 시작합니다.

원격 분석 키 인증으로 전환

이전 시나리오를 확장하여 개발자가 원격 분석 인증으로 돌아가서 엔터티에서 이벤트 로깅을 분리하려는 경우 PFEventPipelineRemoveUploadingEntity를 호출하고 다음과 같이 이벤트 파이프라인 핸들을 전달할 수 있습니다.

void EventPipelineRemoveEntity(PFEventPipelineHandle handle)
{
    HRESULT hr = PFEventPipelineRemoveUploadingEntity(
        handle                  // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed removing uploading entity: 0x%x\r\n", hr);
        return;
    }
}

이 호출은 엔터티를 제거하고 모든 후속 이벤트에 대해 원격 분석 키 인증으로 효과적으로 다시 전환합니다.

파이프라인 구성 업데이트

다음과 같이 기존 이벤트 파이프라인 핸들과 새 구성 구조를 수신하는 PFEventPipelineUpdateConfiguration API를 사용하여 파이프라인을 쉽게 업데이트할 수 있습니다.

void EventPipelineUpdateConfiguration(PFEventPipelineHandle handle)
{
    uint32_t maxEvents = 10;
    uint32_t maxWaitTime = 5;
    uint32_t pollDelay = 50;
    PFHCCompressionLevel compressionLevel = PFHCCompressionLevel::Medium;
    bool retryOnDisconnect = true;
    size_t bufferSize = 2048;

    PFEventPipelineConfig eventPipelineConfig
    {
        &maxEvents,             // maxEventsPerBatch
        &maxWaitTime,           // maxWaitTimeInSeconds
        &pollDelay,             // pollDelayInMs
        &compressionLevel,      // compressionLevel
        &retryOnDisconnect,     // retryOnDisconnect
        &bufferSize,            // bufferSize
    };

    HRESULT hr = PFEventPipelineUpdateConfiguration(
        handle,                 // eventPipelineHandle
        eventPipelineConfig     // eventPipelineConfig
    );

    if (FAILED(hr))
    {
        printf("Failed updating event pipeline configuration: 0x%x\r\n", hr);
        return;
    };
}

알림: 비어 있거나 null인 속성은 기존 구성 값을 기본값으로 덮어씁니다.

유효하지 않거나 비활성화된 원격 분석 키

원격 분석 키가 비활성화되거나 파이프라인 생성 시 잘못된 키가 제공된 경우 해당 원격 분석 키를 사용하여 실행 중인 모든 이벤트 파이프라인은 키가 잘못되었거나 비활성화된 것을 확인하는 즉시 실패하기 시작합니다.

고객이 키를 다시 활성화하는 경우 파이프라인은 이를 인식하지 못하고 실패한 이벤트 처리기를 통해 실패를 다시 보냅니다. 이 동작은 세션 기반이라는 점을 언급할 가치가 있습니다. 즉, 타이틀이 다시 시작되면 새 파이프라인이 생성되고 이벤트를 다시 업로드할 수 있습니다.

참고 항목

이벤트 파이프라인 자습서

다음을 통해 공유