@vivadecora/ng-banner-manager
v1.2.3
Published
Gerenciador de espaços de banners em AngularJs
Downloads
3
Readme
BannerManager
BannerManager é um módulo ES6 feito usando angularJS usado para gerenciar campanhas e espaços publicitários em sistemas que usam angularJS na Viva Decora. Com essa ferramenta é possível:
- Determinar nomes de banners
- Compartilhar configuração de uma campanha para todos os banners da campanha
- Exibir/esconder banners dependendo do breakpoint
- Exibir/esconder banners dependendo de filtros customizados
- Gerenciar campanhas e banners a partir de um único arquivo de configuração
Instalar
Primeiro passo é instalar o módulo em sua aplicação:
Para usuários npm
npm install @vivadecora/vd-banner-manager
Para usuários yarn:
yarn add @vivadecora/vd-banner-manager
Como usar
- Importe o BannerManager no seu projeto angularJS:
import BannerManagerModule from '@vivadecora/vd-banner-manager';
- O BannerManager exporta um módulo angularJS, adicione-o como dependência da sua aplicação seguindo o exemplo abaixo e
sua-aplicacao
deve ficar assim:
import BannerManagerModule from '@vivadecora/vd-banner-manager';
angular.module("sua-aplicacao", [
BannerManagerModuleName
]);
A partir desse momento sua aplicação tem disponível a factory BannerManager
- Injete o
BannerManager
como dependência para inicialização do seu projeto e o inicialize:
angular.module("sua-aplicacao").run(function(BannerManager){
BannerManager.init();
})
- Registre as configurações do BannerManager junto com seu módulo angularJS principal:
import MinhasCampanhas from 'minhas-campanhas.json';
angular.module("sua-aplicacao").run(function(BannerManager){
BannerManager.init();
BannerManager.register(MinhasCampanhas);
})
A seguir mostarmos como criar o MinhasCampanhas
adequado ao padrão do BannerManager:
Arquivo de configuração de campanhas e banners
Partindo do seguinte arquivo de campanha explicaremos os campos aceitos e sua finalidade.
campanha-vivadecora.json
{
"alt": "Campanha Viva Decora",
"target": "https://www.vivadecora.com.br/",
"campaign": "Banner Quarto de Bebê",
"has_border": false,
"title": null,
"title_class": null,
"banners": [{
"unit": "desktop_square",
"url": "https://fotos.vivadecora.com.br/decoracao-quarto-de-bebe-berco-verde-casacor2016-104907-square_cover_xsmall.jpg",
"width": 320,
"height": 320,
"breakpoint": "desktop"
},{
"unit": "mobile_square",
"url": "https://fotos.vivadecora.com.br/decoracao-quarto-de-bebe-berco-verde-casacor2016-104907-square_cover_xsmall.jpg",
"width": 320,
"height": 320,
"breakpoint": "mobile"
}]
}
Os campos da campanha são os seguintes:
|Nome|Descrição|Obrigatório|Valor inicial| Tipo | |-|-|-|-|-| |alt| Texto alternativo que descreve conteúdo da imagem da campanha | Não | null | String | |target| URL absoluta da âncora | Sim | null | String/URL | |campaign| Nome da campanha | Não | null | String | |title| Título que pode ficar acima da imagem do banner | Não | null | String | |title_class| Classe css a ser aplicada ao título acima do banner | Não | null | String |
Os campos de cada item em banners
são os seguintes:
|Nome|Descrição|Obrigatório|Valor inicial| Tipo | |-|-|-|-|-| |unit| Chave única para identificação do banner | Sim | null | String | |url| URL da imagem do banner | Sim | null | String/URL | |width| Largura da imagem do banner | Sim | null | Number | |height| Altura da imagem do banner | Sim | null | Number | |breakpoint| Nome do breakpoint | Sim | "mobile" | String ["mobile", "desktop"] |
Logo ao criar a configuração acima chamada campanha-vivadecora.json
e registra-la via BannerManager.register
teríamos a disposição a seguinte diretiva:
<div data-banner-manager data-unit="desktop_square"></div>
Que irá imprimir um anúncio com a configuração apontada somente para desktops.
Registrando eventos de clique e exibições no init
O BannerManager.init recebe um único objeto de inicialização, dois dos campos aceitos nesse objeto são onClick
e onDisplay
.
- onClick: recebe uma função que determina o que ocorre ao clicar na imagem do banner
- onClick: recebe uma função que determina o que ocorre ao exibir a imagem do banner
Exemplo:
function loBannerEvent(banner, action) {
console.log(`O banner '${banner.unit}' foi ${action}`);
}
BannerManager.init({
onClick: function(banner) {
loBannerEvent(banner, "clicado");
},
onDisplay: function(banner) {
loBannerEvent(banner, "exibido");
},
filters: {
page_id: window.REVISTA.postId
}
});
Nesse caso acima quando o banner de unit exemplo
for clicado deve aparecer uma mensagem:
"O banner 'exemplo' foi clicado."
A implementação dessas funções é livre e pode ser alterada para algo mais útil, por exemplo, envio de informações ao Google Analytics.
Filtrando banners no init
Digamos que você tenha mais de uma campanha ao mesmo tempo. A campanha 1 é exibida para páginas com id 1, 2 e 3 A campanha 2 é exibida para páginas com categoria 9 e 12
Após registrar ambas as campanhas é possível filtrá-las adicionando a seguinte informação a cada uma:
campanha1.json
{
"campaign": "Campanha 1 - Restante do código omitido",
"filters": {
"page_id": [1, 2, 3]
}
}
E a campanha 2:
campanha2.json
{
"campaign": "Campanha 1 - Restante do código omitido",
"filters": {
"category": [9, 12]
}
}
Então você inicializa seu BannerManager e registra ambas:
import campanha1 from "campanha1.json";
import campanha2 from "campanha2.json";
BannerManager.register(campanha1);
BannerManager.register(campanha2);
BannerManager.init({filters: {
page_id: 1
}})
Nesse caso só os itens da campanha 1 serão exibidos.
import campanha1 from "campanha1.json";
import campanha2 from "campanha2.json";
BannerManager.register(campanha1);
BannerManager.register(campanha2);
BannerManager.init({filters: {
category: 9
}})
Nesse caso só os itens da campanha 2 serão exibidos.
Roadmap
- [x] Documentar envio de cliques e exibições para o Analytics
- [x] Permitir filtros dinâmicos
- [ ] Adicionar testes unitários