> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Banners Patrocinados
> Aprenda como usar a API de leilões para criar leilões de listagens e banners.
Integração de Anúncios de Banner: 3 etapas
1. **Configurações de Banner**: Criar e compartilhar espaços publicitários.
2. **Leilões para Banners**: Trabalhar com variáveis de leilão, solicitações e respostas
3. **Renderizar Banners**: renderizar e exibir os assets de banner vencedores
Os anúncios de banner podem ser usados como sliders de página inicial, marcas destacadas e carrosséis.
# **Configurações de Banner**
Forneça uma lista de páginas com identificadores únicos para cada espaço de banner.
## **Landing Pages**: Homepage ou Páginas Personalizadas
Crie espaços para páginas iniciais de alto tráfego ou outras páginas de destino.
Um espaço inclui:
* **SlotID**: Um identificador **único** que pode conter caracteres alfanuméricos e os seguintes símbolos: `!"#$%&'()*+,-._/:;<>?@[]^{}~=`
* **Name**: Um nome descritivo (por exemplo, Homepage Slide 1, Acima dos Produtos em Tendência).
* **URL or Deeplink**: A URL onde o espaço está localizado.
* **Landing Page name**: A página de destino correspondente ao espaço.
* **Largura** e **Altura** de imagem, se necessitar de tamanhos diferentes em dispositivos diferentes, suportamos mais 1 conjunto de tamanhos de imagem
| SlotID | Landing Page Name | URL or Deeplinks | Width | Height | Additional Width (optional) | Additional Height (optional) |
| :----------- | :----------------- | :------------------------------------------------- | :---- | :----- | :-------------------------- | :--------------------------- |
| top-slot-1 | Homepage Christmas | [http://example.com/home](http://example.com/home) | 100 | 50 | 40 | 40 |
| right-slot-2 | Homepage Christmas | [http://example.com/home](http://example.com/home) | 50 | 200 | | |
Use [este arquivo de
amostra](https://docs.google.com/spreadsheets/d/1KMnGnYp6D3u4kwwofm3nZ97Jgwtvys5fqEfGRmO3aVQ/edit#gid=0)
para carregar configurações de banner em massa.
## **Categoria e Busca**
Permita que os vendedores segmentem categorias e palavras-chave específicas. Defina espaços de banner e compartilhe-os.
Exemplo:
| SlotID | Width | Height | Alternative Width (optional) | Alternative Height (optional) |
| :-------------- | :---- | :----- | :--------------------------- | :---------------------------- |
| category-bottom | 100 | 50 | 40 | 40 |
# **Solicitações de Leilão para Banners**
Armazenar o resolvedBidId.
O **resolvedbidId** simplifica a atribuição de eventos e o registro para você e seus vendedores, similar ao **auctionID** em listagens patrocinadas. Precisa ser armazenado para que os eventos possam ser reportados posteriormente, seja como um cookie ou variável de sessão para aplicações web, ou armazenado como uma variável interna para aplicações móveis.
### Campos de Solicitação
| Variable | Type | Definition | Required/optional | Notes |
| :---------- | :------ | :----------------------------------------------- | :----------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
| type | string | Tipo de leilão | required | Deve ser definido como "banners" |
| slots | integer | Número máximo de vencedores do leilão | required | número de vencedores que você gostaria que o leilão retornasse |
| slotId | string | ID de espaço externo fornecido pelo marketplace. | required | Formato: `^[\w!\"#$%&'()_+,\-._/:;<>?@\[\]^\{\}~=\\]\_$` |
| categoryId | string | ID de categoria do marketplace para o leilão. | required apenas se forem banners de categoria | Por padrão é leilão de homepage se não for fornecido ID de categoria. |
| searchQuery | string | | required apenas se forem banners de busca \*pode passar tanto categoryID quanto searchQuery na mesma chamada | Exemplo "blue running shoes" |
| device | string | Dispositivo alvo: desktop ou mobile. | optional | Enum: "desktop" ou "mobile." Por padrão é "desktop." |
### Campos de Resposta
| Variable | Type | Definition |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| resultType | string | "banners" |
| winners.resolvedBidId | string | Um ID da Topsort que será usado quando houver interação com este item (para reportar impressões ou cliques) |
| winners.type | string | Tipo da oferta vencedora. Enum: "product", "vendor", "brand", "url". |
| winners.rank | integer | A classificação do leilão do produto indica sua posição, sendo 1 o vencedor. Na resposta do leilão, o array de vencedores está ordenado, e a classificação corresponde ao índice da entrada. |
| winners.id | string | O ID único do marketplace para a entidade vencedora. |
| winners.asset | array | |
| winners.asset.url | string | URL de origem para um asset de banner. O asset é servido pelo CDN da Topsort, contido no array de assets |
# **Renderizar Banners**
Configure as configurações de banner dentro do painel de administração da Topsort. Insira o banner no DOM da sua aplicação web ou adicione um componente ao código da sua aplicação móvel.
### **Aplicações Web**
Para aplicações web, use o [elemento `picture`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture), que permitirá fornecer múltiplas fontes ao navegador do cliente. Por exemplo, se o asset tiver 2 fontes:
```json theme={null}
"asset": [
{
"url": "https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png",
"mimeType": "image/png",
"dimensions": {
"width": 400,
"height": 100,
}
},
{
"url": "https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-2x.png",
"mimeType": "image/png",
"dimensions": {
"width": 800,
"height": 200,
}
}
]
```
Então você pode gerar o seguinte HTML:
```html theme={null}
```
O navegador do cliente então escolherá o tamanho mais adequado dependendo das capacidades do dispositivo do usuário e obterá apenas o tamanho que melhor se ajusta ao dispositivo do usuário.
### Native iOS (Swift)
Recomendamos usar **[AlamofireImage](https://github.com/Alamofire/AlamofireImage)** para lidar com opções de download e renderização. Você pode obter o fator de escala do dispositivo do seu cliente chamando e escolhendo o tamanho correto.
```swift theme={null}
[UIScreen mainScreen].scale;
```
### No Android (Java)
Use a biblioteca Glide para renderizar e armazenar em cache imagens. Assim como no iOS, você precisará verificar o fator de escala do dispositivo para determinar qual imagem baixar:
```java theme={null}
// Get the screen's density scale
final float scale = getResources().getDisplayMetrics().density;
```
