Modo offline do Game Saves

​

Modos de conexão

​

Modo conectado à nuvem

• Todas as APIs funcionam normalmente, com sincronização completa com a nuvem
• Os uploads de dados de salvamento funcionam conforme o esperado
• As informações de cota de armazenamento estão disponíveis
• O monitoramento do dispositivo ativo funciona corretamente

​

Modo offline (não conectado à nuvem)

​

Tratamento de falhas de rede durante a sincronização inicial

// Handle sync failure callback
void MyPFGameSaveFilesUiSyncFailedCallback(PFLocalUserHandle localUserHandle, PFGameSaveFilesSyncState syncState, HRESULT error, void* context)
{
    // Tell the user something like this:
    std::cout << "We couldn't sync your data with the cloud just now" << std::endl;
    std::cout << "Try syncing again or use this game offline" << std::endl;
    std::cout << "[Try Again]" << std::endl;
    std::cout << "[Use Offline]" << std::endl;

    // if user chooses [Try Again], call PFGameSaveFilesSetUiSyncFailedResponse(localUserHandle, PFGameSaveFilesUiSyncFailedUserAction::Retry);
    // if user chooses [Use Offline], call PFGameSaveFilesSetUiSyncFailedResponse(localUserHandle, PFGameSaveFilesUiSyncFailedUserAction::UseOffline);

    // These API calls can happen inside or outside of this callback
}

• Try Again (Retry): tenta novamente a chamada de rede. Se a nova tentativa também falhar, este retorno de chamada é acionado novamente e o usuário precisa responder outra vez. O retorno de chamada de XAsyncBlock permanece adiado durante cada ciclo de repetição.
• Use Offline (UseOffline): o retorno de chamada de XAsyncBlock é acionado com S_OK, mas o sistema entra no modo offline (detectável com PFGameSaveFilesIsConnectedToCloud()).
• Cancel: o retorno de chamada de XAsyncBlock é acionado com E_PF_GAMESAVE_USER_CANCELLED.

​

Comportamento das APIs no modo offline

​

APIs que funcionam normalmente

• PFGameSaveFilesGetFolder() - Retorna o caminho da pasta de salvamento local

​

APIs com funcionalidade limitada

• PFGameSaveFilesUploadWithUiAsync() - Retorna S_OK imediatamente, mas a conclusão assíncrona retorna E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD
• PFGameSaveFilesGetRemainingQuota() - Retorna E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD
• PFGameSaveFilesSetActiveDeviceChangedCallback() - Pode ser definido, mas nunca será acionado

​

Voltando ao modo online

• Chame PFGameSaveFilesAddUserWithUiAsync() novamente para tentar se reconectar
• Não é necessário reinicializar totalmente o sistema Game Saves
• A interface de falha será exibida novamente se a rede ainda não estiver disponível
• Use PFGameSaveFilesIsConnectedToCloud() para verificar o status da conexão após as tentativas de repetição

​

Quando o Game Saves entra no modo offline ou retorna um erro

• O modo offline é um resultado de êxito, não um erro. Ele só é ativado por uma escolha explícita de Use Offline, e a operação assíncrona é concluída com S_OK. Detecte-o com PFGameSaveFilesIsConnectedToCloud().
• Falhas transitórias/técnicas são exibidas por meio da interface de falha de sincronização, e não retornadas diretamente de PFGameSaveFilesAddUserWithUiAsync. Em seguida, o usuário (ou sua resposta automática) escolhe Retry, UseOffline ou Cancel, o que resulta em um dos três resultados acima.
• O cancelamento é final e não produz uma pasta de salvamento. Trate “cancelado” (ou qualquer falha que não deixe uma pasta) como não permitir jogar.
• O cancelamento pelo jogador e pelo jogo retornam códigos diferentes. Somente o jogador escolhendo Cancel em um aviso produz E_PF_GAMESAVE_USER_CANCELLED. Se o seu jogo cancelar a operação por conta própria com XAsyncCancel, ela será concluída com E_ABORT. Verifique ambos se quiser tratá-los da mesma forma.

​

Códigos de erro do Game Saves

​

Cenários adicionais de status de conexão

• Rede indisponível durante a sincronização: o usuário escolhe explicitamente jogar offline
• Dispositivo ativo alterado: outro dispositivo assume como dispositivo ativo, colocando automaticamente este dispositivo no modo offline

​

Práticas recomendadas para suporte offline

1. Sempre implemente retornos de chamada de falha de sincronização para lidar com problemas de rede de forma adequada
2. Verifique o status da conexão regularmente usando PFGameSaveFilesIsConnectedToCloud() antes de tentar operações na nuvem
3. Informe os jogadores quando estiver operando no modo offline, para que eles entendam que os salvamentos não serão sincronizados
4. Forneça opções de repetição quando a conectividade de rede for restaurada
5. Os salvamentos locais sempre funcionam - os jogadores podem continuar jogando independentemente do status da rede
6. Monitore a desconexão - lembre-se de que os dispositivos podem ser desconectados quando outro dispositivo se torna ativo

​

Comportamento de upload no modo conectado

1. O PFGameSaveFilesUiSyncFailedCallback é acionado com os detalhes do erro.
2. O retorno de chamada de XAsyncBlock ainda não é acionado. A operação fica pausada enquanto o sistema aguarda uma resposta.
3. Se o usuário selecionar Retry, o upload será repetido. Se falhar novamente, o retorno de chamada será acionado outra vez e o usuário precisará responder novamente.
4. Se o usuário selecionar Cancel, o retorno de chamada de XAsyncBlock será acionado com E_PF_GAMESAVE_USER_CANCELLED.
5. Se uma nova tentativa tiver êxito, o retorno de chamada de XAsyncBlock será acionado com S_OK.

​

Quando um upload deixa a sessão offline

• A sessão já estava offline. O upload não é executado e é concluído com E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD, mesmo que a rede tenha sido restaurada.
• A nuvem tem um salvamento mais recente. Se o serviço informar que um salvamento mais recente foi confirmado a partir de outro dispositivo quando o upload for finalizado, o Game Saves coloca a sessão offline, aciona o retorno de chamada de alteração do dispositivo ativo e conclui o upload com E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD.
• O jogador escolhe Use Offline no aviso de novo bloqueio. Se um upload anterior confirmou seus dados, mas falhou depois, o próximo upload primeiro precisa readquirir o bloqueio de salvamento. Um aviso de falha de sincronização durante essa etapa pode ser respondido com UseOffline, o que deixa a sessão offline e conclui o upload com E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD.

​

Cancelando um upload