Este artigo também está disponível em:

Integração Avançada do Código de Integração HTML (widget) via API

<html>
<head>
   <!-- Include the bundles -->
   <script src="https://cdn-apps.drimify.com/prod/widget/index.js" type="text/javascript"></script>

   <!-- Setup the widget on page load -->
   <script>
       window.addEventListener('load', function () {
           var widget = DigitaService.Widget.Create({
               autoscroll: true,
               element: 'gamification-widget',
               engine: 'https://apps.drimify.com/XBs15jKF/',
               fixed: false,
               height:['auto'],
               sharingurl: 'https://apps.drimify.com/XBs15jKF/',
               width: '100%',
           });
           widget.onReady = function (event) {};
           widget.onComplete = function (event) {};
           widget.onFirstInteraction = function () {};
           widget.onRouteChange = function (event) {};
           widget.onScrollToTop = function () {};
           widget.onClose = function () {};
           widget.onError = function (errorEvent) {};
           widget.load();
       });
   </script>
</head>
<body>
<div id="gamification-widget"></div>
</body>
</html>

Configuração

Crie um Widget passando um objeto de opções para a função Create:

var widget = DigitaService.Widget.Create(options);

Opções de Configuração

Necessárias

Opção	Tipo	Descrição
options.element	string - HTMLElement	O widget será injetado neste HTMLElement. Pode-se passar acesso direto a um HTMLElement existente ou fornecer o ID da string para esse elemento. Se não fornecer esta propriedade, tentará encontrar um ID “digitaservice-widget” na página.
options.engine	string	O URL absoluto para a aplicação que será carregada dentro do widget.

Opcionais

Opção	Tipo	Padrão	Descrição
options.height	string	auto	O widget tem uma altura padrão de zero antes de ser carregado. Pode-se substituir isso com um valor de espaço reservado para evitar saltos de página, dependendo do local onde o widget é usado na página principal. O valor está em pixels, como “600px”. Ao usar options.fixed = true, o valor da altura será fixo, introduzindo barras de rolagem.
options.autoscroll	boolean	true	Dependendo do comprimento do conteúdo do widget e da exibição do usuário, pode ser necessário que a página contendo o widget exija rolagem da página de hospedagem. O comportamento padrão quando um usuário utiliza o Widget é rolar a página de hospedagem até o topo do widget para melhorar a usabilidade. Para desativar isso, defina autoscroll como false. Esta propriedade será falsa se options.fixed for true.
options.sharingurl	string	O URL de hospedagem contendo o widget	Ao utilizar Compartilhamento Social, este é o URL que as pessoas compartilharão nas redes sociais para levá-las à sua campanha. Se o compartilhamento for uma string vazia, usará a página de hospedagem (contendo o widget) como o URL.
options.fixed	boolean	false	Normalmente, o widget ajusta automaticamente o tamanho para se adequar ao conteúdo do motor e evitar barras de rolagem. Se isso for definido como true, então a altura do widget será persistente e não mudará. Ao usar esta opção, o valor de options.height deve ser definido para algo diferente de “auto”. Se a altura do motor for maior do que o valor da altura, barras de rolagem serão usadas para navegar.
options.width	string	“100%”	A largura do widget. Pode ser definida para uma medida CSS, como “%” ou “px”, por exemplo.

Carregar

Uma vez que um Widget está configurado, é necessário carregá-lo. Pode-se carregar o widget a qualquer momento.

Nota: Certifique-se de configurar quaisquer callbacks abaixo antes de carregar para que possa captar todos os eventos.

widget.load();

Callbacks de Evento

onReady

Assim que widget.load() for chamado, este irá carregar e inicializar o widget. Quando o widget tiver concluído este processo, invocará um callback opcional onReady.

widget.onReady = function (event) {
   // carregado e preparado para usar
   console.log(event.type); // “ready”
   console.log(event.data); // {}
};

onError

Assim que widget.load() for chamado, este irá carregar e inicializar o widget. Quaisquer erros graves que ocorram depois desse ponto irão invocar um callback opcional onError.

widget.onError = function (event) {
   throw new Error(event.message);
};

onComplete

Quando o jogo estiver concluído e o utilizador estiver a visualizar o último ecrã. Também fornece um data object que descreve o que ocorreu no jogo.

Nota: se quiser agir sobre isto, poderá querer dar um tempo de espera dentro do callback para que o utilizador tenha tempo para ler o Ecrã Final, pois ocorre instantaneamente ao chegar ao último ecrã. Também pode usar onClose.

widget.onComplete = function (event) {
   console.log(event.type); // “complete”
   console.log(event.data); // {}
   console.log("A pontuação do utilizador foi " + event.data.gameMetrics.score);
};

onResize

Ocorre quando o Motor é redimensionado, fornecendo a altura como um valor em pixels.

widget.onResize = function (event) {
   console.log(event.type); // “resize”
   console.log(event.data); // {}
   console.log("Altura da Aplicação:" + event.data.height);
};

onClose

A aplicação pode ser configurada com um botão de fechar dedicado que permite ao utilizador fechar a experiência de forma explícita. Se este botão estiver configurado e o utilizador interagir com ele, então o evento de fechar será disparado. Este é um bom momento para destruir o widget da sua página e acabar com o ciclo de vida do widget.

widget.onClose = function () {
   DigitaService.Widget.Destroy();
};

onFirstInteraction

Quando o utilizador interage (toque/clique) com a aplicação carregada pela primeira vez.

widget.onFirstInteraction = function () {
   console.log("O utilizador interagiu com a Aplicação pela primeira vez");
};

onRouteChange

Ocorre quando a Aplicação muda de rota dentro do widget. (Navega entre ecrãs). O evento pode ou não conter um objeto de dados dependendo do contexto.

widget.onRouteChange = function (event) {
   console.log(event.type) // “routechange”
   console.log(event.data) // {} ou indefinido
   console.log("O utilizador navegou para um novo ecrã");
};

onScrollToTop

Ocorre quando a Aplicação tenta rolar de volta para o topo da página. Pode ser usado na página principal para garantir que a rolagem não é disparada (CORS) ou precisa de ser ajustada. O evento não contém um objeto de dados.

widget.onScrollToTop = function () {
   console.log("Rolar Para o Topo");
};

Métricas

Aqui está uma lista das principais métricas que podem ser usadas dependendo do tipo de jogo:

Chave	Descrição
data.gameMetrics.CurrentAttempt	As tentativas efetuadas pelo utilizador até completar o jogo.
data.gameMetrics.prizeID	A identificação do prémio.
data.gameMetrics.prizeImage	A imagem do prémio.
data.gameMetrics.prizeName	O nome do prémio.
data.gameMetrics.prizeRef	A referência do prémio.
data.gameMetrics.totalPossibleAttempts	A quantidade total de tentativas possíveis.
data.gameMetrics.userWon	Verdadeiro/falso dependendo do estado do utilizador.
data.gameMetrics.score	A quantidade total de pontos acumulados que este utilizador completa o jogo com.

Credenciais

Chave	Descrição
data.credentials.isPreviewMode	Verificar se o jogo está em modo de visualização.
data.credentials.projectID	O id da Aplicação atual jogada.
data.credentials.projectLanguage	O idioma do projeto no widget (en, fr).
data.credentials.projectName	O nome da aplicação.
data.credentials.projectType	O tipo de aplicação (quiz, memória...).
data.credentials.publisherID	O id do publicador.
data.credentials.sessionID	O id da sessão do jogador atual.

Gestão de Erros

Existem duas maneiras principais de detetar erros e obter informações sobre problemas que ocorrem dentro do widget:

Callback onError

O onError callback captura erros fatais que ocorrem após o widget ser carregado. Isso pode ser útil para identificar quando uma página não existe ou se ocorre uma falha crítica.

widget.onError = function (event) {
    if (typeof event.data.message !== 'undefined') {
        switch (event.data.message) {
            padrão:
                // Não fazer nada
                break;
            case 'ERR_15':
                console.log("Página não existe");
                break;
        }
    }
};

Callback onRouteChange

O onRouteChange callback é acionado quando a aplicação navega entre diferentes ecrãs dentro do widget. Isso é útil para rastrear erros relacionados ao estado da aplicação e à disponibilidade de conteúdo.

widget.onRouteChange = function (event) {
    if (typeof event.data.errorCode !== 'undefined') {
        switch (event.data.errorCode) {
            padrão:
                // Não fazer nada
                break;
            case 'ERR_01':
                console.log("Plano não disponível");
                break;
            case 'ERR_02':
                console.log("Conteúdo ainda não disponível");
                break;
            case 'ERR_03':
                console.log("Conteúdo expirado");
                break;
            case 'ERR_04':
                console.log("Sem mais visualizações");
                break;
            case 'ERR_05':
                console.log("Erro de segurança");
                break;
            case 'ERR_07':
                console.log("Aplicação não publicada");
                break;
            case 'ERR_08':
                console.log("Aplicação Premium não disponível");
                break;
            case 'ERR_09':
                console.log("Sessão Uid não detetada");
                break;
            case 'ERR_10':
                console.log("Sessão Uid já usada");
                break;
            case 'ERR_11':
                console.log("Plano não ativado");
                break;
            case 'ERR_12':
                console.log("Dados recebidos incorretos");
                break;
            case 'ERR_13':
                console.log("Falha na chamada SSO");
                break;
            case 'ERR_14':
                console.log("Idioma indisponível");
                break;
        }
    }
};

Utilizando tanto o onError quanto o onRouteChange, consegue-se rastrear e tratar eficazmente problemas que possam surgir dentro do widget, garantindo uma melhor experiência para o utilizador.

Actualizado em: 05/03/2025

Esse artigo foi útil?

Obrigado!