@vivadecora/ng-banner-manager

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

1. Importe o BannerManager no seu projeto angularJS:

import BannerManagerModule from '@vivadecora/vd-banner-manager';

2. 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

3. Injete o BannerManager como dependência para inicialização do seu projeto e o inicialize:

angular.module("sua-aplicacao").run(function(BannerManager){
    BannerManager.init();
})

5. 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