> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 이벤트 파이프라인 튜토리얼

> PlayFab Services SDK 이벤트 파이프라인 생성을 위한 단계별 튜토리얼: 초기화, 텔레메트리 키 인증, 이벤트 방출, 엔터티 첨부 및 닫기.

이 문서는 PlayFab Services SDK의 이벤트 파이프라인 기능을 사용하는 방법에 대한 빠른 단계별 튜토리얼입니다.

## 1단계 - PlayFab Services SDK 초기화

첫 번째 단계는 [**PFServicesInitialize**](/services/playfab/api-references/c/pfservices/functions/pfservicesinitialize) 및 [**PFServiceConfigCreateHandle**](/services/playfab/api-references/c/pfserviceconfig/functions/pfserviceconfigcreatehandle) API를 사용하여 PF Service SDK를 초기화하는 것입니다.

**PFServiceConfigCreateHandle** API는 PlayFab Game Manager의 타이틀에서 얻을 수 있는 연결 문자열과 타이틀 ID를 받습니다.

세 번째 파라미터는 생성 중인 구성을 나타내는 **PFServiceConfigHandle** 구조체입니다. 이 서비스 구성 핸들은 다음 단계에서 사용됩니다.

```cpp theme={null}
PFServiceConfigHandle serviceConfigHandle;

PFServicesInitialize(nullptr);

PFServiceConfigCreateHandle(
    "titleConnectionString",
    "titleId",
    &serviceConfigHandle
);
```

## 2단계 - 텔레메트리 이벤트 파이프라인 만들기

다음으로, [**PFEventPipelineCreateTelemetryPipelineHandleWithKey**](/services/playfab/api-references/c/pfeventpipeline/functions/pfeventpipelinecreatetelemetrypipelinehandlewithkey) API를 사용하여 텔레메트리 키로 텔레메트리 이벤트 파이프라인을 만들어 보겠습니다. 텔레메트리 키는 PlayFab Game Manager를 통해 생성 및 관리됩니다.

PFEventPipelineTelemetryKeyConfig 구조체를 만들 때, 실제 텔레메트리 키와 SDK 초기화 중에 얻은 서비스 구성 핸들을 전달합니다.

```cpp theme={null}
PFEventPipelineHandle handle;
XTaskQueueHandle taskQueueHandle;

XTaskQueueCreate(XTaskQueueDispatchMode::ThreadPool, XTaskQueueDispatchMode::Manual, &taskQueueHandle);

PFEventPipelineTelemetryKeyConfig telemetryKeyConfig
{
    "myTelemetryKey",
    serviceConfigHandle,
};

HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithKey(
    &telemetryKeyConfig,
    taskQueueHandle,
    nullptr,
    nullptr,
    nullptr,
    &handle
);

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

## 3단계 - 파이프라인 구성 업데이트

파이프라인 구성을 업데이트해 보겠습니다. 이 예제에서는 최대 10개 이벤트의 배치를 보내려고 합니다(기본값은 5).

또한 maxWaitTimeInSeconds 및 pollDelayInMs를 null 포인터로 보내고 있기 때문에 각 파이프라인 타입에 대한 기본값을 사용합니다.

또한 "Medium" 압축 수준을 지정하고 있으며, 이 속성을 설정하면 본문 페이로드가 압축되어 네트워크 리소스 활용을 최적화하는 데 도움이 됩니다.

그런 다음 이전 단계에서 얻은 **PFEventPipelineHandle**과 **PFEventPipelineConfig** 구조체를 전달하여 [**PFEventPipelineUpdateConfiguration**](/services/playfab/api-references/c/pfeventpipeline/functions/pfeventpipelineupdateconfiguration)을 호출합니다.

```cpp theme={null}
uint32_t maxEvents = 10;
PFHCCompressionLevel compressionLevel = PFHCCompressionLevel::Medium;

PFEventPipelineConfig eventPipelineConfig
{
    &maxEvents,         // maxEventsPerBatch
    nullptr,            // maxWaitTimeInSeconds
    nullptr,            // pollDelayInMs
    &compressionLevel   // compressionLevel
};

HRESULT hr = PFEventPipelineUpdateConfiguration(
    handle,
    eventPipelineConfig
);

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

## 4단계 - 이벤트 방출

이 단계에서, [**PFEventPipelineEmitEvent**](/services/playfab/api-references/c/pfeventpipeline/functions/pfeventpipelineemitevent) API를 통해 "TelemetryKeyEvent"라는 이름의 이벤트 1개만 방출합니다.

지금까지 엔터티 인증을 제공하지 않았기 때문에 이 이벤트는 어떤 엔터티와도 연결되지 않습니다.

```cpp theme={null}
PFEvent myEvent
{
    nullptr,
    "custom.playfab.events.PlayFab.Test.TelemetryEventPipelineTests",
    "TelemetryKeyEvent",
    nullptr,
    "{}"
};

HRESULT hr = PFEventPipelineEmitEvent(
    handle,
    &myEvent
);

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

## 5단계 - 엔터티 가져오기

여기서 이벤트에 연결하기 위해 사용할 수 있는 엔터티를 가져오려고 합니다.

이 튜토리얼에서는 유효한 **PFEntityHandle**을 얻기 위해 [**PFAuthenticationReLoginWithXUserAsync**](/services/playfab/api-references/c/pfauthentication/functions/pfauthenticationreloginwithxuserasync) API를 호출하고 있습니다.

<Note>
  **PFAuthenticationLoginWithXUserRequest**의 일부로 전달된 userHandle 오브젝트는 XUserHandle 타입입니다. 유효한 XUserHandle을 가져오는 방법에 대한 단계는 이 튜토리얼의 범위를 벗어납니다. 이 주제에 대한 자세한 내용은 [XUserAddAsync](/reference/system/xuser/functions/xuseraddasync) 문서를 참조하세요.
</Note>

```cpp theme={null}
PFEntityHandle entityHandle;

PFAuthenticationLoginWithXUserRequest request{};
request.createAccount = true;
request.user = userHandle; // An XUserHandle obtained from XUserAddAsync

XAsyncBlock async{};

HRESULT hr = PFAuthenticationReLoginWithXUserAsync(entityHandle, &request, &async);

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

hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage

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

## 6단계 - 파이프라인에 엔터티 추가

이미 유효한 엔터티를 얻었기 때문에, [**PFEventPipelineAddUploadingEntity**](/services/playfab/api-references/c/pfeventpipeline/functions/pfeventpipelineadduploadingentity)를 호출하고 이벤트 파이프라인 핸들과 이전 단계의 엔터티 핸들을 전달할 수 있습니다. 이 작업을 통해 파이프라인은 엔터티 인증을 사용하도록 전환할 수 있습니다.

```cpp theme={null}
HRESULT hr = PFEventPipelineAddUploadingEntity(
    handle,
    entityHandle
);

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

## 7단계 - 이벤트 방출

이 절차는 이전 이벤트 제출과 동일합니다.

두 가지 차이점만 있습니다:

* 명확성을 위해 이 이벤트를 다른 이름("EntityEvent")으로 태그하고 있습니다.
* 이 이벤트는 이전에 얻은 엔터티와 로깅되고 연결됩니다.

```cpp theme={null}
PFEvent myEvent
{
    nullptr,
    "custom.playfab.events.PlayFab.Test.TelemetryEventPipelineTests",
    "EntityEvent",
    nullptr,
    "{}"
};

hr = PFEventPipelineEmitEvent(
    handle,
    &myEvent
);

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

## 8단계 - 이벤트 파이프라인 핸들 닫기

마지막으로, 이벤트 업로드가 완료되면 파이프라인 핸들을 전달하여 [**PFEventPipelineCloseHandle**](/services/playfab/api-references/c/pfeventpipeline/functions/pfeventpipelineclosehandle)을 호출하기만 하면 됩니다.

```cpp theme={null}
PFEventPipelineCloseHandle(handle);
```

## 참고 항목

* [이벤트 파이프라인 개요](/services/playfab/sdks/c/event-pipeline/eventpipeline)


## Related topics

- [PlayFab Services SDK - 이벤트 파이프라인](/ko/services/playfab/sdks/c/event-pipeline/eventpipeline.md)
- [Services C API 개요 - PFEventPipeline.h](/ko/services/playfab/api-references/c/pfeventpipeline/pfeventpipeline_members.md)
- [이벤트 예제 코드](/ko/services/xbox-services/player-data/stats-leaderboards/event-based/events/how-to/live-events-howto-nav.md)
- [PFEventPipelineEmitEvent](/ko/services/playfab/api-references/c/pfeventpipeline/functions/pfeventpipelineemitevent.md)
- [PlayFab 지원 언어](/ko/services/playfab/sdks/languages/index.md)