Configuração

Crie um Widget passando um objeto Options para a função Create:

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

Opções de Configuração

Obrigatório

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

Opcional

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 alterar isso com um valor de espaço reservado para evitar saltos na página dependendo de onde o widget é usado na página pai. O valor está em pixels, como “600px”. Ao usar options.fixed = true, o valor da altura será fixo para o valor fornecido, introduzindo barras de rolagem.
options.autoscroll	booleano	true	Dependendo do comprimento do conteúdo do widget e da exibição do usuário, pode ser necessário que a página que contém o widget precise de rolagem na página hospedeira. O comportamento padrão quando um usuário está utilizando o Widget é rolar a página hospedeira para o topo do widget para melhorar a usabilidade. Para desativar isso, defina autoscroll como false. Esta propriedade será false se options.fixed for true.
options.sharingurl	string	O URL hospedeiro contendo o widget	Ao usar Partilha Social, este é o URL que as pessoas compartilharão nas Redes Sociais para as direcionar para a sua campanha. Se a partilha for uma string vazia, usará a página hospedeira (contendo o widget) como o URL.
options.fixed	booleano	false	Normalmente o widget mudará de tamanho automaticamente para se ajustar ao conteúdo do engine e evitar barras de rolagem. Se definido como true, a altura do widget será persistente e não mudará. Ao usar esta opção, o valor options.height deve ser definido para qualquer coisa diferente de “auto”. Se a altura do engine for maior do que o valor de altura, as barras de rolagem serão usadas para navegação.
options.width	string	“100%”	A largura do widget. Pode ser definida para uma medida CSS como “%” ou “px”, por exemplo.

Carregar

Depois de configurar um Widget, deve carregá-lo. Pode carregar o widget a qualquer momento.

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

```widget.load();```# Event Callbacks

onReady

Depois de widget.load() ter sido chamado, o widget será carregado e inicializado. Quando este processo estiver concluído, um callback opcional onReady será invocado.

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

onError

Após widget.load() ter sido chamado, o widget será carregado e inicializado. Quaisquer erros fatais ocorridos após este ponto irão invocar um callback opcional onError.

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

onComplete

Quando o jogo for concluído e o utilizador estiver a ver o ecrã final. Fornece também um data object descrevendo o que ocorreu no jogo.

Nota: se quiser agir sobre isto, poderá querer definir um timeout dentro do callback para que o utilizador tenha tempo de ler a Tela Final, pois ocorre instantaneamente ao chegar ao ecrã final. 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 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 dedicado para fechar, que permite ao utilizador fechar a experiência implicitamente. Se este botão estiver configurado e o utilizador interagir com ele, o evento fechar será acionado. Este é um bom momento para destruir o widget na sua página e terminar 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 mudou 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 undefined
   console.log("O utilizador interagiu com a Aplicação pela primeira vez");
};

onScrollToTop

Ocorre quando a Aplicação tenta realizar scroll para o topo da página. Pode ser usado na página pai para garantir que o scroll não seja disparado (CORS) ou precise de ajustes. O evento não contém um objeto de dados.

```widget.onScrollToTop = function () {
console.log("Scroll para o Topo");
};```# Métricas

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

Chave	Descrição
data.gameMetrics.CurrentAttempt	As tentativas que o utilizador fez após completar o jogo.
data.gameMetrics.prizeID	O ID 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	true/false dependendo do estado do utilizador.
data.gameMetrics.score	A quantidade total de pontos acumulados com que o utilizador termina o jogo.

Credenciais

Chave	Descrição
data.credentials.isPreviewMode	Verifica 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 publisher.
data.credentials.sessionID	O id da sessão do jogador atual.

Actualizado em: 22/02/2025