Início rápido: Android

Comece a usar o SDK do PlayFab Services para Android. Siga estas etapas para incluir as bibliotecas no seu projeto e experimentar o código de exemplo da funcionalidade básica do PlayFab. Este início rápido ajuda você a fazer sua primeira chamada à API do PlayFab usando o SDK para Android. Antes de continuar, verifique se você concluiu as etapas de Início rápido: Game Manager, que garantem que você tenha uma conta do PlayFab e esteja familiarizado com o PlayFab Game Manager.

Requisitos

Uma conta de desenvolvedor do PlayFab.
Android Studio instalado.

Configuração do projeto

Baixe o SDK do PlayFab para Android para o seu projeto na página de releases do SDK do PlayFab.

Integrar o SDK do PlayFab para C ao seu projeto

As próximas etapas foram escritas considerando que você criou um novo projeto usando o Android Studio.

Adicionar os binários ao seu jogo

Há duas partes dos binários que você precisará integrar ao seu projeto: os arquivos de objeto compartilhado (.so) e os arquivos de arquivamento do Android (.aar). Você pode compilar os binários por conta própria ou baixá-los da página de releases.

Adicionando os arquivos .so

Esses arquivos são integrados ao seu projeto usando o CMake.

Descompacte o release do SDK do PlayFab para Android e coloque o conteúdo no diretório desejado.
Usando target_include_directories ou outra função equivalente, adicione os cabeçalhos em “Include” do release do SDK do PlayFab:

TARGET_INCLUDE_DIRECTORIES(
    ${PROJECT_NAME}
    "Include"
)

Usando target_link_libraries ou outra função equivalente, vincule os locais dos arquivos .so ao seu projeto. Por exemplo:

set(PLAYFAB_SERVICES_PATH "[LOCATION OF YOUR FILE]/libPlayFabServices.Android.so")

set(PLAYFAB_CORE_PATH "[LOCATION OF YOUR FILE]/libPlayFabCore.Android.so")

set(LIBHTTPCLIENT_PATH "[LOCATION OF YOUR FILE]/libHttpClient.Android.so")

TARGET_LINK_LIBRARIES(
    [YOUR PROJECT NAME]
    ${PLAYFAB_SERVICES_PATH}
    ${PLAYFAB_CORE_PATH}
    ${LIBHTTPCLIENT_PATH}
)

Adicionando os arquivos .aar

Esses arquivos são integrados ao seu projeto usando o Gradle.

Crie uma pasta libs no diretório do projeto Android no nível do aplicativo. Veja um exemplo de como o diretório do seu projeto deve ficar agora:

Copie os arquivos .aar para a pasta libs.
No arquivo build.gradle no nível do aplicativo, aquele no mesmo diretório da pasta libs, adicione estas linhas à seção de dependências. A segunda linha é necessária como dependência do libHttpClient.

implementation fileTree(dir: 'libs', include: ['*.aar'])
implementation 'com.squareup.okhttp3:okhttp:4.9.1'

Agora que seu projeto está totalmente configurado para usar o SDK do PlayFab Services para Android, siga as próximas etapas para fazer algumas chamadas de exemplo funcionarem.

Configuração inicial

Primeiro, você precisará configurar seu aplicativo para ter uma instância de uma activity do Android. Você também precisará configurar um pequeno aplicativo C/C++ para usar o NDK com a JNI (Java Native Interface). Veja um pequeno exemplo de referência: https://github.com/android/ndk-samples/tree/android-mk/hello-jni. O exemplo contém um método nativo que retorna um jstring:

jstring Java_com_example_hellojni_HelloJni_stringFromJNI(JNIEnv* env, jobject thiz)

Métodos nativos podem ser usados para obter a Java VM e o contexto do aplicativo, dois itens necessários para inicializar o PFServices. Você pode criar um método semelhante para fins de inicialização:

void Java_com_example_hellojni_HelloJni_InitializeApp(JNIEnv* env, jobject appContext)

A Java VM pode então ser recuperada usando a variável JNIEnv.

    JavaVM* javaVM = nullptr;
    jint res = env->GetJavaVM(&javaVM);
    if (res != JNI_OK)
    {
        // error handling
    }

Em seguida, o contexto do aplicativo pode ser obtido com o parâmetro jobject.

    applicationContext = env->NewGlobalRef(appContext);

Agora que você armazenou essas duas variáveis, podemos começar a fazer chamadas.

Cabeçalhos

Inclua PFServices.h para ter acesso a toda a funcionalidade do PlayFab incluída:

#include <playfab/services/PFServices.h>

Inicialização

A inicialização do PlayFab requer duas chamadas de função: PFServicesInitialize e PFServiceConfigCreateHandle. O resultado dessa inicialização é um PFServiceConfigHandle. Você fornece esse identificador a uma chamada de login subsequente, direcionando a chamada para o título correto no back-end do PlayFab.

    HCInitArgs initArgs;
    // Use the Java VM and application context from earlier
    initArgs.javaVM = javaVm;
    initArgs.applicationContext = applicationContext;

    HRESULT hr = PFServicesInitialize(nullptr, &initArgs); // Add your own error handling when FAILED(hr) == true

    PFServiceConfigHandle serviceConfigHandle{ nullptr };

    hr = PFServiceConfigCreateHandle(
            "https://ABCDEF.playfabapi.com",    // PlayFab API endpoint - obtained in the Game Manager
            "ABCDEF",                           // PlayFab Title id - obtained in the Game Manager
            &serviceConfigHandle);

Depois de ter um PFServiceConfigHandle, você pode usá-lo para fazer uma chamada de login de jogador. No SDK, use um método PFAuthenticationLoginWith*Async, como PFAuthenticationLoginWithCustomIDAsync. Essa função permite fazer login de um jogador no PlayFab usando uma ID personalizada. Depois de fazer uma chamada de login, você pode verificar o status da chamada com XAsyncGetStatus. O status começa como E_PENDING e muda para S_OK depois que a chamada é concluída com êxito. Se a chamada falhar por algum motivo, o status refletirá essa falha. O tratamento de erros em todas as chamadas do PlayFab Services funciona dessa forma. Junto com um resultado S_OK, você recebe um PFEntityHandle. Use esse identificador para fazer as chamadas subsequentes do PlayFab como o jogador conectado. Ele inclui todo o material necessário para se autenticar no serviço PlayFab como esse jogador.

    PFAuthenticationLoginWithCustomIDRequest request{};
    request.createAccount = true;
    request.customId = "player1";

    XAsyncBlock async{};
    HRESULT hr = PFAuthenticationLoginWithCustomIDAsync(serviceConfigHandle, &request, &async); // Add your own error handling when FAILED(hr) == true
    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

    std::vector<char> loginResultBuffer;
    PFAuthenticationLoginResult const* loginResult;
    size_t bufferSize;
    hr = PFAuthenticationLoginWithCustomIDGetResultSize(&async, &bufferSize);
    loginResultBuffer.resize(bufferSize);

    PFEntityHandle entityHandle{ nullptr };
    hr = PFAuthenticationLoginWithCustomIDGetResult(&async, &entityHandle, loginResultBuffer.size(), loginResultBuffer.data(), &loginResult, nullptr);

Chamadas de serviço

Depois de fazer login do jogador, você pode fazer chamadas ao back-end do PlayFab. Veja um exemplo de chamada para obter os arquivos armazenados no PlayFab para o jogador atual.

Obtendo a EntityKey

Algo que pode ser útil em algumas chamadas ao PlayFab é conhecer a PFEntityKey do jogador. Depois de ter um PFEntityToken, você pode recuperar uma PFEntityKey com PFEntityGetEntityKey.

    PFEntityKey const* pEntityKey{};
    std::vector<char> entityKeyBuffer;
    size_t size{};
    HRESULT hr = PFEntityGetEntityKeySize(entityHandle, &size); // Add your own error handling when FAILED(hr) == true

    entityKeyBuffer.resize(size);
    hr = PFEntityGetEntityKey(entityHandle, entityKeyBuffer.size(), entityKeyBuffer.data(), &pEntityKey, nullptr);

Chamando GetFiles

Todas as chamadas do PlayFab seguem um padrão semelhante: preparar o objeto de solicitação, fazer a chamada (usando o PFEntityHandle do login), criar um objeto para receber a resposta e, em seguida, chamar uma função GetResult para preencher o contêiner recém-criado.

    XAsyncBlock async{};
    PFDataGetFilesRequest requestFiles{};
    requestFiles.entity = pEntityKey;

    HRESULT hr = PFDataGetFilesAsync(entityHandle, &requestFiles, &async); // Add your own error handling when FAILED(hr) == true
    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

    size_t resultSize;
    hr = PFDataGetFilesGetResultSize(&async, &resultSize);

    std::vector<char> getFilesResultBuffer(resultSize);
    PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
    hr = PFDataGetFilesGetResult(&async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);

Limpeza

Quando seu jogo estiver pronto para ser desligado ou você precisar limpar o PlayFab por algum outro motivo, feche todos os identificadores abertos e chame PFServicesUninitializeAsync.

    PFEntityCloseHandle(entityHandle);
    entityHandle = nullptr;

    PFServiceConfigCloseHandle(serviceConfigHandle);
    serviceConfigHandle = nullptr;

    XAsyncBlock async{};
    HRESULT hr = PFServicesUninitializeAsync(&async); // Add your own error handling when FAILED(hr) == true
    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

Padrão de API assíncrona

O SDK do PlayFab Services segue o modelo de programação assíncrona implementado no GDK. Esse modelo de programação envolve o uso de tarefas e filas de tarefas fornecidas pela biblioteca XAsync. Esse modelo é consistente com outras funções e extensões do GDK (como a API do XBOX Services). Embora introduza alguma complexidade, ele também oferece um alto grau de controle sobre as operações assíncronas. Este exemplo mostra como fazer uma chamada assíncrona a PFDataGetFilesAsync.

    auto async = std::make_unique<XAsyncBlock>();
    async->callback = [](XAsyncBlock* async)
    {
        std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // take ownership of XAsyncBlock

        size_t resultSize;
        HRESULT hr = PFDataGetFilesGetResultSize(async, &resultSize);
        if (SUCCEEDED(hr))
        {
            std::vector<char> getFilesResultBuffer(resultSize);
            PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
            PFDataGetFilesGetResult(async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);
        }
    };

    PFDataGetFilesRequest requestFiles{};
    requestFiles.entity = m_pEntityKey;
    HRESULT hr = PFDataGetFilesAsync(m_entityHandle, &requestFiles, async.get());
    if (SUCCEEDED(hr))
    {
        async.release(); // at this point, the callback will be called so release the unique ptr
    }

Tratamento de erros

As operações XAsync concluídas retornam códigos de status HTTP. Um código de status de erro se manifesta como um HRESULT de falha, como HTTP_E_STATUS_NOT_FOUND, ao chamar XAsyncGetStatus() ou uma das APIs PF*Get(). Para ver as mensagens de erro detalhadas retornadas pelo serviço, consulte a próxima seção sobre depuração. Essas mensagens de erro detalhadas podem ser úteis durante o desenvolvimento para entender melhor como o serviço PlayFab reage às solicitações do cliente.

Depuração

A maneira mais fácil de ver os resultados e depurar qualquer chamada no SDK do PlayFab Services é habilitar o rastreamento de depuração. Habilitar o rastreamento de depuração permite tanto ver os resultados na janela de saída do depurador quanto conectar os resultados aos logs do próprio jogo.

Referência

Documentação de referência da API

​Início rápido: Android

​Requisitos

​Configuração do projeto

​Integrar o SDK do PlayFab para C ao seu projeto

​Adicionar os binários ao seu jogo

​Adicionando os arquivos .so

​Adicionando os arquivos .aar

​Inicialização e login

​Configuração inicial

​Cabeçalhos

​Inicialização

​Fazendo login

​Chamadas de serviço

​Obtendo a EntityKey

​Chamando GetFiles

​Limpeza

​Padrão de API assíncrona

​Tratamento de erros

​Depuração

​Referência