SDK Lifecycle

This page covers the complete startup and shutdown sequence for the PlayFab Services SDK. Every title follows the same high-level pattern: configure optional hooks, initialize Core, create a service configuration, initialize Services, do work, then shut down in reverse order.

Initialization sequence

Initialization has four steps. The first is optional; the remaining three are required.

PFMemSetFunctions (optional)  →  PFInitialize  →  PFServiceConfigCreateHandle  →  PFServicesInitialize

Step 1: Set custom memory hooks (optional)

If your title uses a custom memory allocator, call PFMemSetFunctions before any other PlayFab API. This routes all SDK memory allocations through your own alloc and free callbacks.

PFMemoryHooks hooks{};
hooks.alloc = MyAllocFunction;
hooks.free = MyFreeFunction;
HRESULT hr = PFMemSetFunctions(&hooks);

PFMemSetFunctions must be called before PFInitialize. It can’t be called again after hooks have been set.

If you don’t need custom memory management, skip this step. The SDK uses default allocation routines.

Step 2: Initialize PlayFab Core

PFInitialize sets up the SDK’s global state, including the HTTP layer and background task queue. The exact signature varies by platform.

Windows, Linux, iOS, and macOS

HRESULT hr = PFInitialize(nullptr); // Uses a default threadpool queue

Pass an XTaskQueueHandle if you want to control which queue handles background work. Pass nullptr to use the default threadpool queue.

Android

On Android, you must also provide the Java VM and application context so the SDK can initialize libHttpClient:

HRESULT hr = PFInitialize(nullptr, javaVm, applicationContext);

If you don’t call PFInitialize explicitly, PFServicesInitialize calls it internally with default parameters. This is fine for most titles. However, if you’re using custom memory hooks via PFMemSetFunctions, you must call PFInitialize yourself — otherwise PFServicesInitialize initializes Core before your memory hooks take effect, and the SDK uses default allocation routines instead.

Step 3: Create a service configuration

PFServiceConfigCreateHandle creates a handle that tells the SDK which PlayFab title and endpoint to target. You’ll find both values in Game Manager.

PFServiceConfigHandle serviceConfigHandle{ nullptr };
HRESULT hr = PFServiceConfigCreateHandle(
    "https://ABCDEF.playfabapi.com",    // API endpoint from Game Manager
    "ABCDEF",                           // Title ID from Game Manager
    &serviceConfigHandle);

The returned PFServiceConfigHandle is required for all subsequent login calls.

Step 4: Initialize PlayFab Services

PFServicesInitialize sets up the Services layer (Inventory, Leaderboards, Friends, and so on) on top of Core.

Windows, Linux, iOS, and macOS

HRESULT hr = PFServicesInitialize(nullptr);

The parameter is reserved for future use; pass nullptr.

Android

On Android, pass an HCInitArgs struct containing the Java VM and application context:

HRESULT hr = PFServicesInitialize(nullptr, initArgs);

After this call succeeds, the SDK is ready. You can log in players and make service calls.

PFServiceConfigHandle lifecycle

A PFServiceConfigHandle is a ref-counted handle. The SDK manages its internal lifetime through reference counting, but you’re responsible for closing every handle you own.

Function	Description
PFServiceConfigCreateHandle	Creates a new handle. The initial ref count is 1.
PFServiceConfigDuplicateHandle	Increments the ref count and returns a second handle. Both handles must be closed independently.
PFServiceConfigCloseHandle	Decrements the ref count. When it reaches 0, the config is destroyed.
PFServiceConfigGetAPIEndpoint	Retrieves the API endpoint string. Call PFServiceConfigGetAPIEndpointSize first to determine the buffer size.
PFServiceConfigGetTitleId	Retrieves the title ID string. Call PFServiceConfigGetTitleIdSize first to determine the buffer size.

Duplicating a handle

Use PFServiceConfigDuplicateHandle when you need to share a service config across components that manage their own lifetimes:

PFServiceConfigHandle duplicatedHandle{ nullptr };
HRESULT hr = PFServiceConfigDuplicateHandle(serviceConfigHandle, &duplicatedHandle);

// Both handles are now valid and must be closed separately
PFServiceConfigCloseHandle(duplicatedHandle);
PFServiceConfigCloseHandle(serviceConfigHandle);

Shutdown sequence

Shutdown is the reverse of initialization. You must uninitialize Services before Core, and both calls are asynchronous.

Close handles  →  PFServicesUninitializeAsync  →  PFUninitializeAsync

Step 1: Close all open handles

Before tearing down the SDK, close every PFEntityHandle and PFServiceConfigHandle you own:

PFEntityCloseHandle(entityHandle);
entityHandle = nullptr;

PFServiceConfigCloseHandle(serviceConfigHandle);
serviceConfigHandle = nullptr;

Step 2: Uninitialize Services

PFServicesUninitializeAsync tears down the Services layer. Wait for it to complete before proceeding.

XAsyncBlock asyncServices{};
HRESULT hr = PFServicesUninitializeAsync(&asyncServices);
hr = XAsyncGetStatus(&asyncServices, true); // Blocking wait

Step 3: Uninitialize Core

After Services cleanup finishes, call PFUninitializeAsync to tear down Core:

XAsyncBlock asyncCore{};
HRESULT hr = PFUninitializeAsync(&asyncCore);
hr = XAsyncGetStatus(&asyncCore, true); // Blocking wait

If you didn’t call PFInitialize explicitly, you can skip PFUninitializeAsync. In that case, PFServicesUninitializeAsync handles Core cleanup automatically. However, if you did call PFInitialize yourself, you must call PFUninitializeAsync yourself.

Complete example

This example shows the full lifecycle from initialization through shutdown on a Windows title:

#include <playfab/services/PFServices.h>

void RunPlayFab()
{
    //
    // Optional: set custom memory hooks
    //
    PFMemoryHooks hooks{};
    hooks.alloc = MyAllocFunction;
    hooks.free = MyFreeFunction;
    HRESULT hr = PFMemSetFunctions(&hooks);

    //
    // Initialize Core
    //
    hr = PFInitialize(nullptr);

    //
    // Create a service configuration
    //
    PFServiceConfigHandle serviceConfigHandle{ nullptr };
    hr = PFServiceConfigCreateHandle(
        "https://ABCDEF.playfabapi.com",
        "ABCDEF",
        &serviceConfigHandle);

    //
    // Initialize Services
    //
    hr = PFServicesInitialize(nullptr);

    //
    // Log in a player (Windows example using XUser)
    //
    PFAuthenticationLoginWithXUserRequest request{};
    request.createAccount = true;
    request.user = userHandle;

    XAsyncBlock asyncLogin{};
    hr = PFAuthenticationLoginWithXUserAsync(serviceConfigHandle, &request, &asyncLogin);
    hr = XAsyncGetStatus(&asyncLogin, true);

    size_t bufferSize{};
    hr = PFAuthenticationLoginWithXUserGetResultSize(&asyncLogin, &bufferSize);

    std::vector<char> loginResultBuffer(bufferSize);
    PFAuthenticationLoginResult const* loginResult{};
    PFEntityHandle entityHandle{ nullptr };
    hr = PFAuthenticationLoginWithXUserGetResult(
        &asyncLogin, &entityHandle,
        loginResultBuffer.size(), loginResultBuffer.data(),
        &loginResult, nullptr);

    //
    // ... make service calls ...
    //

    //
    // Shutdown: close handles first
    //
    PFEntityCloseHandle(entityHandle);
    entityHandle = nullptr;

    PFServiceConfigCloseHandle(serviceConfigHandle);
    serviceConfigHandle = nullptr;

    //
    // Shutdown: uninitialize Services, then Core
    //
    XAsyncBlock asyncServices{};
    hr = PFServicesUninitializeAsync(&asyncServices);
    hr = XAsyncGetStatus(&asyncServices, true);

    XAsyncBlock asyncCore{};
    hr = PFUninitializeAsync(&asyncCore);
    hr = XAsyncGetStatus(&asyncCore, true);
}

Common mistakes

Mistake	What happens	Fix
Calling PFMemSetFunctions after PFInitialize	The call fails. Memory hooks can only be set before initialization.	Move PFMemSetFunctions to the very first PlayFab call in your program.
Calling PFUninitializeAsync before PFServicesUninitializeAsync	Undefined behavior. Core is torn down while Services still depends on it.	Always uninitialize Services first, wait for completion, then uninitialize Core.
Forgetting to call PFUninitializeAsync after explicit PFInitialize	Core resources leak. The background queue and HTTP layer aren’t cleaned up.	If you called PFInitialize, you must call PFUninitializeAsync.
Not waiting for async uninitialize to complete	The process may exit while cleanup is still in progress, causing crashes or hangs.	Use `XAsyncGetStatus(async, true)` or an XAsyncBlock callback to wait for completion.
Leaking PFServiceConfigHandle or PFEntityHandle	Ref-counted resources aren’t freed and may prevent clean shutdown.	Close every handle you create or duplicate before calling uninitialize.

XBOX Services

PlayFab

Initialization sequence

Step 1: Set custom memory hooks (optional)

Step 2: Initialize PlayFab Core

Windows, Linux, iOS, and macOS

Android

Step 3: Create a service configuration

Step 4: Initialize PlayFab Services

Windows, Linux, iOS, and macOS

Android

PFServiceConfigHandle lifecycle

Duplicating a handle

Shutdown sequence

Step 1: Close all open handles

Step 2: Uninitialize Services

Step 3: Uninitialize Core

Complete example

Common mistakes

See also

​Initialization sequence

​Step 1: Set custom memory hooks (optional)

​Step 2: Initialize PlayFab Core

​Windows, Linux, iOS, and macOS

​Android

​Step 3: Create a service configuration

​Step 4: Initialize PlayFab Services

​Windows, Linux, iOS, and macOS

​Android

​PFServiceConfigHandle lifecycle

​Duplicating a handle

​Shutdown sequence

​Step 1: Close all open handles

​Step 2: Uninitialize Services

​Step 3: Uninitialize Core

​Complete example

​Common mistakes

​See also

Initialization sequence

Step 1: Set custom memory hooks (optional)

Step 2: Initialize PlayFab Core

Windows, Linux, iOS, and macOS

Android

Step 3: Create a service configuration

Step 4: Initialize PlayFab Services

Windows, Linux, iOS, and macOS

Android

PFServiceConfigHandle lifecycle

Duplicating a handle

Shutdown sequence

Step 1: Close all open handles

Step 2: Uninitialize Services

Step 3: Uninitialize Core

Complete example

Common mistakes

See also