Visão geral

O Digital Distribution Hub é uma solução que conecta desenvolvedores de jogos com vários parceiros de distribuição que têm suas próprias plataformas ou ecossistemas para a distribuição de jogos, itens virtuais, moedas virtuais e conjuntos.

Parceiros de distribuição — plataformas digitais ou ecossistemas que podem distribuir jogos e itens de jogo e ter sua própria loja e faturamento. Exemplos de parceiros de distribuição Xsolla:

• superaplicativos que agrupam vários serviços
• aplicativos bancários
• provedores de serviços de telecomunicações e internet
• quiosques de dinheiro
• cashback e provedores de programas de recompensa
• mercados de comércio eletrônico

Benefícios para o desenvolvedor de jogos:

• Expansão do público dos jogos por meio de uma conexão direta com parceiros de distribuição em rápido crescimento.
• Aumento da receita adicionando jogos a novos canais de distribuição com uma base de usuários exclusiva.
• Aumento da capacidade de descoberta orgânica em plataformas de terceiros por meio de anúncios e banners.

Benefícios para o parceiro de distribuição:

• Aumento da fidelidade de seus usuários expandindo o acesso ao conteúdo do jogo. Os usuários podem comprar chaves de jogo, itens virtuais, moedas virtuais e conjuntos diretamente a partir aplicativo ou serviço.
• Retenção de usuários atuais e atração de novos usuários através da crescente popularidade da indústria de jogos.
• Aumento da receita da comissão de venda de chaves de jogos, itens virtuais e moedas virtuais de grandes editoras da indústria de jogos.

Como funciona

Fluxo do usuário ao comprar chaves de jogo

Fluxo de usuário ao comprar itens virtuais e moedas virtuais

Fluxo de interação

1. O desenvolvedor do jogo cria um projeto na Conta de Distribuidor e carrega as chaves de jogo, itens virtuais, moedas virtuais e conjuntos.
2. Um parceiro de distribuição solicita dados do usuário:
   • ao vender jogos — o endereço de e-mail do usuário para o qual as chaves e o recibo serão enviados
   • ao vender itens de jogo — o ID do jogo do usuário ao qual os itens serão adicionados e o endereço de e-mail do usuário para o qual o recibo será enviado
3. O usuário insere os seguintes dados na interface do parceiro de distribuição:
   • para compras de jogos — o endereço de e-mail para receber as chaves e recibo
   • para compras de itens de jogo — ID do jogo para adicionar os itens ao inventário e um endereço de e-mail para receber o recibo
4. O parceiro de distribuição chama o método Create user token e passa o endereço de e-mail (obrigatório) e o ID do usuário (obrigatório ao vender itens virtuais, moedas virtuais e conjuntos) como parâmetros.
5. A Xsolla verifica se o usuário existe no jogo se o desenvolvedor do jogo tem webhooks configurados. A configuração de webhooks é necessária para a venda de itens virtuais e moedas virtuais, mas opcional para chaves de jogo.
6. A Xsolla cria um token com dados do usuário e envia o token para o parceiro de distribuição.
7. O parceiro de distribuição solicita um catálogo de jogos ou um catálogo de itens do jogo.
8. A Xsolla retorna o catálogo solicitado na resposta.
9. O parceiro de distribuição recebe o catálogo e o exibe para o usuário.
10. O usuário faz uma compra. O parceiro de distribuição cria um carrinho.
11. O parceiro de distribuição envia o carrinho do usuário para criar um pedido.
12. A Xsolla devolve o ID do pedido e o preço do carrinho, incluindo descontos e impostos.
13. O parceiro de distribuição exibe o custo total do carrinho para o usuário.
14. Se o usuário continuar com o pagamento, o parceiro de distribuição debitará os fundos do usuário e exibirá a página de status do pagamento.
15. O parceiro de distribuição notifica a Xsolla de que o pedido foi pago e envia informações de pagamento.
16. A Xsolla notifica o desenvolvedor do jogo sobre a compra.
17. O usuário que comprou o jogo recebe um e-mail com os detalhes da compra e pode ativar as chaves de jogo. Se o usuário comprou itens virtuais ou moedas virtuais, elas são adicionadas ao inventário dele.

Integração do lado do desenvolvedor de jogos

Como conectar o Digital Distribution Hub

1. Conecte a Store na Conta de Distribuidor e baixe:
   • chaves de jogo ou conjuntos de chaves de jogo, se você vende chaves de jogo
   • itens virtuais, moedas virtuais ou conjutnos, se você vende itens de jogo
2. Configure webhooks.
3. Entre em contato com o seu Gerente de Sucesso do Cliente ou envie um e-mail a csm@xsolla.com para ativar o Digital Distribution Hub no seu projeto.

Como configurar webhooks

A configuração do Webhook é necessária:

• para validar o usuário e personalizar o catálogo por ID de usuário no jogo
• para validar o usuário e adicionar itens comprados no jogo ao seu inventário
• para vincular o ID de transação do lado da Xsolla com o ID de transação no sistema do desenvolvedor do jogo
• para passar parâmetros de usuário adicionais na ordem
• para receber notificações de compra

Para configurar webhooks:

1. Abra seu projeto em Conta de Distribuidor.
2. Clique em Project settings no menu lateral e vá para Webhooks.
3. Defina a configuração Webhooks como On.
4. Especifique a URL do webhook.
5. É gerada uma chave secreta para assinar webhooks do projeto por padrão. Se quiser gerar uma nova chave secreta, clique no ícone de atualização.
6. Clique em Save settings.

Validação do usuário

A Xsolla envia um webhook User validation para verificar se um usuário existe no jogo. A validação do usuário permite que você:

• exiba um catálogo personalizado para o usuário se você passar atributos de usuário na resposta
• adicionar itens ao inventário do usuário após a compra

Para confirmar o recebimento do webhook, seu servidor deve retornar:

• Código HTTP 204 sem um corpo de mensagem, se o usuário existir no jogo
• Código HTTP 400 descrevendo o problema, se o usuário especificado não foi encontrado ou se uma assinatura inválida foi passada

A lista completa e o mecanismo de webhooks, incluindo exemplos, são descritos em detalhes na Referência da API.

Em resposta, você pode passar parâmetros de transação adicionais no objeto custom_parameters.

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"additionalProperties": false,
"properties": {
  "user_attributes": {
    "type": "object",
    "required": false,
    "minProperties": 1,
    "maxProperties": 100,
    "patternProperties": {
      "^[\\w-_.]{1,255}$": {
        "oneOf": [
          {
            "type": "integer"
          },
          {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 255
            },
            "minItems": 1,
            "maxItems": 1000
          }
        ]
      }
    },
    "additionalProperties": false
  }
}
}

Exemplo da resposta:

{
  "user_attributes": {
    "age": 18,
    "level": 1,
    "game": "WoW",
    "is_baned": false,
    "registration_date": "2022-01-01"
  }
}

Vinculação de ID da transação

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "notification_type": {
      "type": "string"
    },
    "order_id": {
      "type": "integer"
    },
    "project_id": {
      "type": "integer"
    },
    "user": {
      "type": "object",
      "properties": {
        "external_id": {
          "type": "string"
        },
        "email": {
          "type": "string"
        }
      }
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "item_id": {
            "type": "integer"
          },
          "sku":  {
            "type": "string"
          },
          "quantity": {
            "type": "integer"
          },
          "type": {
            "type": "string"
          }
        }
      }
    }
  }
}

Exemplo de solicitação:

{
  "notification_type": "create_external_transaction",
  "order_id": 1,
  "project_id": 51336,
  "user": {
    "external_id": "user_id",
    "email": "public_email@test.com"
  },
  "items": [
    {
      "item_id": 101,
      "sku": "mithril_dagger",
      "quantity": 2,
      "type": "virtual_good"
    }
  ]
}

Em resposta, você pode passar parâmetros de transação adicionais no objeto custom_parameters.

Resposta esperada:

{
  "id": "validation_transaction_info_response.json",
 "$schema": "http://json-schema.org/draft-07/schema#",
 "description": "DDH Project Transaction Info Response",
 "type": "object",
 "additionalProperties": true,
 "properties": {
   "id": {
     "type": "string",
     "minLength": 1
   },
  "custom_parameters": {
     "type": "object",
     "additionalProperties": true,
     "minProperties": 1,
     "maxProperties": 200
   }
 }
}

Exemplo da resposta:

{
    "id":"123"
}

Lista de parâmetros de webhook para vincular IDs de transação:

Notificação de compra

• O webhook de pagamento que contém informações de pagamento.
• O webhook de conteúdos do carrinho, que contém informações sobre os itens a serem adicionados ao inventário.

Integração no lado do parceiro de distribuição

Se você estiver interessado em integrar o Digital Distribution Hub, envie um e-mail para o gerente de integração no endereço psbusiness@xsolla.com e obtenha os parâmetros necessários para trabalhar com o Digital Distribution Hub API:

• geotype
• project_id
• distribution_hub_id e api_key

Durante a integração, você precisa enviar notificações sobre pagamentos bem-sucedidos ou cancelamentos (etapa 9). Para processar corretamente as notificações no lado da Xsolla, informe seu gerente sobre o endereço IP do servidor a partir do qual você envia as notificações. Se o endereço IP for alterado, certifique-se de informar o gerente assim que possível.

1. Exiba um formulário para inserir:
   • o endereço de e-mail do usuário — ao vender jogos
   • o endereço de e-mail e o ID do jogo — ao vender itens do jogo

1. O ID do usuário é usado para projetos que vendem itens virtuais, moedas virtuais e pacotes com itens e moedas. Nesse caso, também é necessário exibir uma dica para que o usuário insira o ID que recebeu ao se cadastrar no jogo.

1. Exemplo:

2. Passe os dados de usuário recebidos:
   • Endereço de e-mail do usuário. Sempre obrigatório.
   • ID do usuário no jogo. Obrigatório ao vender itens de jogo.

1. Os dados são usados para verificar a existência do usuário no jogo e receber um token de autorização.

1. Use o método Create user token. Passe parâmetros na solicitação:

1. Um token de autorização com dados do usuário é retornado na resposta.

3. Importe:
   • catálogos de jogos, usando o método Obter lista de jogos
   • catálogo de itens virtuais, usando o método de lista Obter item virtual
   • catálogo de moedas virtuais, usando o método Obter lista de moedas virtuais
   • conjuntos com jogos ou catálogos de itens de jogo, usando o método Gets a list of bundles

1. Na solicitação, passe o token que você recebeu na etapa 2 e o seguinte parâmetro:

4. Exiba o catálogo de jogos e itens de jogo em sua vitrine. Na interface, implemente a habilidade de selecionar:
   • o número de chaves de jogo e plataformas de publicação de jogos
   • o número de itens virtuais
   • o número de moedas virtuais ou pacotes de moedas virtuais com uma quantidade fixa de moedas
   • o número de conjuntos

1. Se você usar um carrinho, o número de itens pode ser especificado no carrinho do usuário. Se você não usar um carrinho, a escolha do número de itens pode ser implementada no catálogo.

1. Exemplo para especificar o número de itens no carrinho:

1. Exemplo para especificar o número de itens no catálogo:

1. Se você não usar um carrinho, vá para a etapa 6 e use o método Criar pedido com item especificado.

5. Para preencher o carrinho, use o método Fill the cart with items.

1. O usuário pode adicionar e remover itens ou alterar sua quantidade em um pedido. Você pode usar o seguinte para atualizar o carrinho:
   • o método Encher o carrinho com itens toda vez que o usuário alterar os conteúdos do carrinho
   • métodos para atualizar o carrinho e excluir um item:
     • Atualizar item de carrinho no carrinho atual
     • Excluir todos os itens do carrinho atual
     • Excluir item do carrinho atual

1. Nesse caso, use Obter o carrinho do usuário atual depois de atualizar o carrinho.

1. Passe os seguintes parâmetros em solicitações de métodos de preenchimento e atualização de carrinho:

1. Depois de chamar Fill the cart with items ou Obter o carrinho do usuário atual, a resposta retorna informações atualizadas sobre os produtos selecionados — preços antes e depois de descontos, produtos bônus.

6. Para criar um pedido e pagar por itens em um carrinho, use o método Criar pedido com todos os itens do carrinho atual. Passe os seguintes parâmetros na solicitação:

1. A resposta retorna o ID do pedido e o preço do carrinho, incluindo impostos.

7. Exiba o preço total do carrinho ao usuário.
8. Debite os fundos do usuário de sua plataforma. Exiba o status de pagamento ao usuário.
9. Envie uma notificação de pagamento. Se o pagamento foi reembolsado ou não concluído, envie uma notificação sobre cancelamento de pagamento.

1. Para processar notificações corretamente no lado da Xsolla, informe o gerente da Xsolla sobre o endereço IP do servidor a partir do qual você envia notificações. Se o endereço IP mudar, certifique-se de informar o gerente assim que possível.