> ## 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.
# Lojas e promoções no Economy (Legado)
> Crie lojas do PlayFab Economy Legado a partir do seu catálogo e execute promoções temporárias com preços personalizados em moeda virtual ou dinheiro real para itens selecionados.
# Lojas e promoções (Economy Legado)
As APIs do Economy v1 estão em modo de manutenção e não receberão novos recursos, apenas correções de bugs. **As APIs v1 serão mantidas no futuro próximo.** Consulte a [Visão geral do Economy v2](/pt-BR/services/playfab/economy-monetization/economy-v2/overview) para saber mais sobre a próxima versão do PlayFab Economy!
No PlayFab, as **Lojas** são criadas com base em [Catálogos](/pt-BR/services/playfab/economy-monetization/economy/items/catalogs) e [Moedas](/pt-BR/services/playfab/economy-monetization/economy/tutorials/currencies). Seu catálogo principal deve definir todos os itens do seu jogo e atribuir a eles preços nas moedas que você criou.
As lojas devem definir subconjuntos dos itens do seu catálogo e disponibilizá-los para compra a preços específicos que podem ser diferentes dos preços do catálogo.
Uma loja permite selecionar um conjunto específico de itens e disponibilizá-los a preços específicos por um período definido.
Este tutorial ilustra as práticas recomendadas para definir lojas com base em moeda virtual e dinheiro real.
## Requisitos
* Familiaridade com o [Game Manager](/pt-BR/services/playfab/live-service-management/gamemanager/quickstart) do PlayFab.
* Você deve ter definido uma ou mais [Moedas virtuais](/pt-BR/services/playfab/economy-monetization/economy/tutorials/currencies). O último exemplo deste tutorial usa:
* **SP** (**Peças de prata**)
* **GP** (**Peças de ouro**).
* Você deve ter um *catálogo principal* com um ou mais itens definidos.
* O primeiro exemplo usa vários itens/pacotes, semelhantes aos descritos no tutorial [Tabelas de drop](/pt-BR/services/playfab/economy-monetization/economy/tutorials/drop-tables).
* O segundo exemplo deste tutorial usa poções de vida pequenas, médias e grandes.
### Práticas recomendadas
Os preços do catálogo devem ser fixos a longo prazo - eles definem o preço *real* de um item.
As lojas devem ser *temporárias*, sendo adicionadas e removidas de acordo com suas estratégias de LiveOps.
Espere obter a maior parte da sua receita alternando lojas e fazendo a transição de itens para dentro e para fora das lojas ativas.
## Informações gerais sobre lojas e preços do catálogo
* **Preços**: os preços definidos no catálogo devem ser definidos como o preço *normal* de um item. As lojas permitem definir um preço promocional temporário para um item, utilizando a tática comum do varejo. Como alternativa, as lojas podem oferecer um preço temporário para um item que normalmente não está disponível para venda.
* **Custo zero**: se o custo de um item em uma determinada moeda não estiver definido (**null**) ou for **zero**, ele não poderá ser comprado usando essa moeda, tanto em catálogos quanto em lojas. O custo zero permite disponibilizar itens exclusivamente para moedas gratuitas ou exclusivamente para moedas premium, deixando em branco as entradas das outras moedas ou redefinindo-as como **zero**.
* **Dinheiro real**: a moeda **RM** está disponível em todos os catálogos e lojas. RM é uma chave de moeda restrita que indica *somente transações com dinheiro real*. Você só deve cobrar RM por itens de valor significativo ou por pacotes/contêineres com moeda premium.
* **Os preços são um ou outro**: se dois preços forem definidos em um item, o item poderá ser comprado com um ou com o outro. *Não é possível* exigir duas moedas para um único item.
## Definindo uma loja com dinheiro real
No seu **Game Manager**:
* Navegue até seu **Título**.
* Selecione **Economy** no menu à esquerda.
* Na guia **Catálogos**, selecione seu catálogo principal e selecione **Lojas**.
* Selecione o botão **Nova loja**.
No exemplo de [Tabelas de drop](/pt-BR/services/playfab/economy-monetization/economy/tutorials/drop-tables), criamos um pacote de drop com 11 itens. Para este exemplo, disponibilizaremos três pacotes semelhantes em uma loja com dinheiro real.
Qualquer item pode ser vendido por dinheiro real, mas é uma prática recomendada disponibilizar diretamente apenas itens ou pacotes valiosos *específicos*.
A captura de tela abaixo mostra uma nova **Loja** completa, contendo três **Pacotes de itens** disponíveis por **Dinheiro real**.
Os detalhes para concluir compras com dinheiro real são abordados em nosso tutorial avançado, [processamento de pagamentos sem recibo](/pt-BR/services/playfab/economy-monetization/economy/tutorials/non-receipt-payment-processing).
### Práticas recomendadas para lojas com dinheiro real
A forma como você usa dinheiro real depende muito do design específico do seu jogo. A compra direta de itens do jogo é válida, mas menos comum.
Mais tipicamente, seu jogo deve permitir a compra de uma moeda virtual premium usando dinheiro real. Você pode alternar várias lojas com diferentes proporções de moeda premium para dinheiro real.
A principal lição é: garanta que seus jogadores *sempre* possam dar dinheiro a você.
## Definindo uma loja com moeda virtual
Vamos entrar nos detalhes e no código para comprar itens do jogo com moeda virtual.
As etapas iniciais são quase idênticas às do exemplo anterior:
1. Crie três novos itens: **Poções de vida pequena**, **média** e **grande** com um preço em **Moeda** *gratuita* e um preço em **Moeda** *premium*.
2. Crie uma nova loja com os itens em promoção.
## Comprando vários itens em uma única compra
Para comprar um único item com moeda virtual, use o método [PurchaseItem](xref:titleid.playfabapi.com.client.playeritemmanagement.purchaseitem), conforme descrito em nosso [Início rápido de lojas](/pt-BR/services/playfab/economy-monetization/economy/stores/quickstart). Este tutorial aborda a compra de vários itens em uma única compra.
Sua primeira etapa nesse processo deve ser obter a loja e exibi-la ao usuário.
```csharp theme={null}
void GetVcStore()
{
var primaryCatalogName = "TestCatalog-001"; // In your game, this should just be a constant matching your primary catalog
var storeId = "Potion Store"; // In your game, this should be a constant for a permanent store, or retrieved from titleData for a time-sensitive store
var request = new GetStoreItemsRequest
{
CatalogVersion = primaryCatalogName,
StoreId = storeId
};
PlayFabClientAPI.GetStoreItems(request, LogSuccess, LogFailure);
}
```
O retorno de chamada `LogSuccess` neste exemplo recebe um [GetStoreItemsResult](xref:titleid.playfabapi.com.client.title-widedatamanagement.getstoreitems#getstoreitemsresult) que contém uma descrição completa de todos os itens da loja, seus preços *da loja* e quaisquer metadados contidos na própria loja.
### Práticas recomendadas para exibir lojas
Jogos com lojas devem chamar e armazenar em cache seu catálogo principal usando o método [GetCatalogItems](xref:titleid.playfabapi.com.server.title-widedatamanagement.getcatalogitems). Você pode exibir tanto o preço do catálogo quanto o preço da loja, junto com uma decoração de 10% DE DESCONTO ou bônus semelhante ao lado dos itens em promoção.
Os jogadores têm mais probabilidade de comprar itens em promoção, especialmente se a promoção for uma oferta por tempo limitado.
Neste ponto, é responsabilidade do seu código de GUI apresentar ao usuário a oportunidade de selecionar quais itens deseja comprar e em que quantidade.
* Entre seu jogo e o PlayFab, as etapas restantes são várias chamadas de API separadas, mas você pode tornar a sequência de várias chamadas invisível para o jogador.
* Colete todas as informações sobre a compra antecipadamente e faça a sequência completa de chamadas depois que *toda* a entrada do jogador for coletada.
```csharp theme={null}
void DefinePurchase()
{
var primaryCatalogName = "TestCatalog-001"; // In your game, this should just be a constant matching your primary catalog.
var storeId = "Potion Store"; // At this point in the process, it's just maintaining the same storeId used above.
var request = new StartPurchaseRequest
{
CatalogVersion = primaryCatalogName,
StoreId = storeId,
Items = new List {
// The presence of these lines are based on the results from GetStoreItems, and user selection - Yours will be more generic.
new ItemPurchaseRequest { ItemId = "Small Health Potion", Quantity = 20,},
new ItemPurchaseRequest { ItemId = "Medium Health Potion", Quantity = 100,},
new ItemPurchaseRequest { ItemId = "Large Health Potion", Quantity = 2,},
}
};
PlayFabClientAPI.StartPurchase(request, result => { Debug.Log("Purchase started: " + result.OrderId); }, LogFailure);
}
```
Durante o processo de seleção de itens, você deve permitir que o usuário selecione qual moeda deseja gastar nesses itens. Neste exemplo, todos os itens têm custos em **SP** e **GP**, o que significa que o usuário pode escolher qual moeda gastar.
O [resultado](xref:titleid.playfabapi.com.client.playeritemmanagement.startpurchase#startpurchaseresult) da API `StartPurchase` no exemplo de código acima contém uma lista de `PaymentOptions`. Cada opção de pagamento contém `Currency`, `Price` e `ProviderName` que podem ser usados para fazer a compra.
### Restrições
Apenas *uma* moeda virtual é permitida em uma única compra. Todos os itens selecionados devem poder ser comprados com uma *única moeda*.
A moeda deve ser especificada na chamada, o que é importante quando há várias moedas possíveis. A sequência falhará se houver itens na solicitação sem custos correspondentes na moeda selecionada.
O `ProviderName` também deve ser especificado na chamada. Para compras com dinheiro real, o nome do provedor é quem é usado para financiar a compra, como Facebook, PayPal ou Steam. Para compras com VC, será uma cadeia de caracteres baseada no ID do seu título. O `ProviderName` pode ser obtido do campo `PaymentOptions` de [StartPurchaseResult](xref:titleid.playfabapi.com.client.playeritemmanagement.startpurchase#startpurchaseresult), conforme descrito na **Observação** anterior.
Para compras com VC, o `ProviderName` do seu título é uma cadeia de caracteres construída a partir da palavra "Title" concatenada com o equivalente decimal do seu `TitleId` hexadecimal. Por exemplo, "Title123456".
### Práticas recomendadas para exibir itens da loja
Evite confundir seu jogador garantindo que todos os itens de uma loja tenham opções consistentes.
Itens de dinheiro real devem ficar em uma loja separada dos itens de VC premium e, novamente, separados dos itens de VC gratuita. Se uma única loja permitir várias moedas, *todos* os itens dessa loja devem usar de forma consistente o mesmo conjunto de várias moedas. Crie quantas lojas forem necessárias para oferecer uma experiência tranquila ao cliente.
```csharp theme={null}
void DefinePaymentCurrency(string orderId, string currencyKey, string providerName)
{
var request =new PayForPurchaseRequest {
OrderId = orderId, // orderId comes from StartPurchase above.
Currency = currencyKey, // User defines which currency they wish to use to pay for this purchase (all items must have a defined/non-zero cost in this currency).
ProviderName = providerName // providerName comes from the PaymentOptions in the result from StartPurchase above.
};
PlayFabClientAPI.PayForPurchase(request, LogSuccess, LogFailure);
}
```
Por fim, quando a compra estiver totalmente definida, você poderá concluir o processo, conforme mostrado abaixo.
```csharp theme={null}
// Unity/C#
void FinishPurchase(string orderId)
{
var request = new ConfirmPurchaseRequest { OrderId = orderId };
PlayFabClientAPI.ConfirmPurchase(request, LogSuccess, LogFailure);
}
```
### Práticas recomendadas para lidar com resultados de falha da API
Qualquer chamada de API pode falhar por muitos motivos. Dispositivos sem fio, como telefones, geralmente podem ter conectividade intermitente, e qualquer chamada pela internet pode falhar devido a latência aleatória.
Cada chamada deve verificar várias condições de falha. Você deve anular se a resposta mostrar que a solicitação é inválida (por exemplo, não é possível comprar vários itens com uma única moeda). Pode haver problemas com o design da sua loja.
Se a resposta indicar uma falha de conectividade, você poderá tentar novamente com um atraso de retirada exponencial.
## Conclusão
As lojas são um ótimo mecanismo para incentivar seus jogadores a comprar itens.
As lojas funcionam com qualquer tipo de moeda virtual. As lojas também podem funcionar com dinheiro real por meio de um conjunto alternativo de métodos de API.
* Você pode configurar uma compra de um único item com VC via [PurchaseItem](xref:titleid.playfabapi.com.client.playeritemmanagement.purchaseitem).
* Você pode configurar uma compra de vários itens com dinheiro real ou VC por meio da sequência:
* [StartPurchase](xref:titleid.playfabapi.com.client.playeritemmanagement.startpurchase)
* [PayForPurchase](xref:titleid.playfabapi.com.client.playeritemmanagement.payforpurchase)
* [ConfirmPurchase](xref:titleid.playfabapi.com.client.playeritemmanagement.confirmpurchase)
Para obter mais informações sobre compras com dinheiro real, consulte [Processamento de pagamentos sem recibo](/pt-BR/services/playfab/economy-monetization/economy/tutorials/non-receipt-payment-processing).
Para o uso avançado de lojas, consulte o tutorial [Lojas personalizadas para segmentos de jogadores](/pt-BR/services/playfab/economy-monetization/economy/tutorials/custom-stores-for-player-segments).
## Related topics
- [Lojas (Economy Legado)](/pt-BR/services/playfab/economy-monetization/economy/stores/index.md)
- [Início rápido de lojas (Economy Legado)](/pt-BR/services/playfab/economy-monetization/economy/stores/quickstart.md)
- [Lojas personalizadas para segmentos de jogadores no Economy (Legacy)](/pt-BR/services/playfab/economy-monetization/economy/tutorials/custom-stores-for-player-segments.md)
- [Consumíveis temporizados no Economy (Legado)](/pt-BR/services/playfab/economy-monetization/economy/tutorials/timed-consumables.md)
- [Cupons e promoções no Economy (Legacy)](/pt-BR/services/playfab/economy-monetization/economy/tutorials/coupons-and-promotions.md)