> ## 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.

# Início rápido iOS

> Adicione o SDK do PlayFab Services para C a um projeto do Xcode e faça sua primeira chamada à API do PlayFab a partir de um aplicativo iOS criado com a biblioteca de cliente nativa para C.

# Início rápido: iOS

Comece a usar o SDK do PlayFab Services para iOS. 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 iOS. Antes de continuar, verifique se você concluiu as etapas de [Início rápido: Game Manager](/pt-BR/services/playfab/live-service-management/gamemanager/quickstart), que garantem que você tenha uma conta do PlayFab e esteja familiarizado com o PlayFab Game Manager.

## Requisitos

* Uma [conta de desenvolvedor do PlayFab](https://developer.playfab.com).
* IDE [XCode](https://developer.apple.com/xcode/) instalado.

## Configuração do projeto

Baixe o SDK do PlayFab para iOS para o seu projeto na [página de releases do SDK do PlayFab](https://github.com/PlayFab/PlayFabCSdk/releases/latest).

### Integrar o SDK do PlayFab para C ao seu projeto

#### Adicionar os binários ao seu jogo

Depois de obter seus binários por download ou compilando a partir do código-fonte, você poderá integrá-los facilmente ao seu jogo/aplicativo. Você precisa adicionar os seguintes binários ao seu jogo:

* HttpClient\_iOS.xcframework
* PlayFabCore\_iOS.xcframework
* PlayFabServices\_iOS.xcframework

Siga estas instruções para adicioná-los:

1. No XCode, navegue até o destino desejado e selecione-o.

2. Na seção **General**, role para baixo e, na seção "**Frameworks, Libraries, and Embedded Content**", selecione o sinal "**+**".

3. Pesquise seus binários **PlayFabServices** / **PlayFabCore** / **HttpClient** e selecione as pastas xcframework. (*Você também pode selecionar uma biblioteca específica navegando dentro das pastas xcframework, mas é recomendável importar o pacote xcframework, pois ele funciona tanto para builds de dispositivo quanto de simulador.*)

4. Depois que os binários forem importados com êxito, HttpClient\_iOS, PlayFabCore\_iOS e PlayFabServices\_iOS serão listados em Frameworks, Libraries, and Embedded Content.

#### Adicionar os caminhos de pesquisa de cabeçalhos

Depois que os binários forem adicionados, você precisará garantir que os caminhos de pesquisa de cabeçalhos também estejam configurados corretamente.

1. Navegue até o seu projeto.

2. Selecione "**Build Settings**" e pesquise "**Header Search Paths**".

3. Atualize o valor da propriedade para incluir os cabeçalhos do SDK. Adicione uma referência aos cabeçalhos encontrados na pasta **include**. Exemplo:
   ```
   PlayFabCSdk-iOS/include
   ```

## Inicialização e login

Siga as próximas etapas para fazer algumas chamadas de exemplo do PlayFab funcionarem.

### Cabeçalhos

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

```cpp theme={null}
#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.

```cpp theme={null}
    HRESULT hr = PFServicesInitialize(nullptr); // 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);
```

### Fazendo login

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 **PFAuthenticationLoginWithAppleAsync**. Essa função permite fazer login de um jogador no PlayFab usando o **token de identidade de um usuário da Apple**. (*consulte a documentação da Apple sobre [Authenticating users with Sign in with Apple](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api/authenticating_users_with_sign_in_with_apple)*).

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.

```cpp theme={null}
PFAuthenticationLoginWithAppleRequest request{};
request.createAccount = true;
request.identityToken = identityToken; // A user identity token obtained from Apple

XAsyncBlock async{};
hr = PFAuthenticationLoginWithAppleAsync(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 = PFAuthenticationLoginWithAppleGetResultSize(&async, &bufferSize);
loginResultBuffer.resize(bufferSize);

PFEntityHandle entityHandle{ nullptr };
hr = PFAuthenticationLoginWithAppleGetResult(&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**.

```cpp theme={null}
    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.

```cpp theme={null}
    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**.

```cpp theme={null}
    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](https://learn.microsoft.com/en-us/gaming/gdk/_content/gc/system/overviews/async-programming-model) implementado no GDK. Esse modelo de programação envolve o uso de tarefas e filas de tarefas fornecidas pela [biblioteca XAsync](/pt-BR/build/core-features/common/async/async-libraries/async-library-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**.

```cpp theme={null}
    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](/pt-BR/services/playfab/sdks/c/tracing). 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.

## Confira também

[Documentação de referência da API](/pt-BR/services/playfab/api-references/c/pfauthentication/pfauthentication_members)


## Related topics

- [Linguagens compatíveis com o PlayFab](/pt-BR/services/playfab/sdks/languages/index.md)
- [Plataformas compatíveis com o PlayFab](/pt-BR/services/playfab/sdks/platforms/index.md)
- [Início rápido do Party](/pt-BR/services/playfab/multiplayer/networking/quickstart.md)
- [Início rápido de prevenção contra fraudes](/pt-BR/services/playfab/economy-monetization/economy-v2/fraud-prevention/quickstart.md)
- [Início rápido de notificações por push](/pt-BR/services/playfab/live-service-management/game-configuration/title-communications/push-notifications/quickstart.md)