Integração Avançada do Código de Integração HTML (widget) via API
Código de exemplo do Widget
<html>
<head>
<!-- Incluir os pacotes -->
<script src="https://cdn-apps.drimify.com/prod/widget/index.js" type="text/javascript"></script>
<!-- Configurar o widget ao carregar a página -->
<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 Options para a função Create:
var widget = DigitaService.Widget.Create(options);
Opções de Configuração
Obrigatórios
Opção | Tipo | Descrição |
|---|---|---|
options.element | string - HTMLElement | O widget será injetado neste HTMLElement. Pode passar acesso direto a um HTMLElement existente ou fornecer a string ID para esse elemento. Se não fornecer esta propriedade, irá tentar encontrar um ID “digitaservice-widget” na página. |
options.engine | string | O URL absoluto para a aplicação que será carregada no 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 substituir isto por um valor de placeholder para evitar saltos na página dependendo de onde o widget é utilizado na página mãe. O valor está em pixels como “600px”. Quando usa options.fixed = true, o valor da altura será fixado no valor fornecido, introduzindo barras de rolagem. |
options.autoscroll | boolean | true | Dependendo do comprimento do conteúdo do widget e do ecrã do utilizador, pode ser necessário que a página que contém o widget exija rolar para visualizar. O comportamento padrão, quando um utilizador está a usar o Widget, é rolar a página mãe até ao topo do widget para facilitar a usabilidade. Para desativar isto, defina autoscroll como false. Esta propriedade será false se options.fixed for true. |
options.sharingurl | string | O URL de hospedagem que contém o widget | Ao utilizar a Partilha Social, este é o URL que as pessoas irão partilhar nas Redes Sociais para levá-las à sua campanha. Se sharing estiver vazio, utilizará a página de hospedagem (que contém o widget) como o URL. |
options.fixed | boolean | false | Normalmente, o widget alterará automaticamente de tamanho para adaptar-se ao conteúdo do motor e evitar barras de rolagem. Se isto estiver definido como true, então a altura do widget será persistente e não mudará. Ao utilizar esta opção, o valor de options.height deve ser definido como qualquer coisa exceto “auto”. Se a altura do motor for maior que o valor da altura, as 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 configurado um Widget, deve carregá-lo. Pode carregar o widget a qualquer momento.
Nota: Certifique-se de configurar qualquer um dos callbacks abaixo antes de carregar para que possa capturar todos os eventos.
widget.load();
```# Chamadas de Evento
###### onReady
Após chamar *widget.load()*, o widget será carregado e inicializado. Quando este processo estiver concluído, o widget invocará uma callback opcional *onReady*.
widget.onReady = function (event) {
// carregado e pronto para uso
console.log(event.type); // “ready”
console.log(event.data); // {}
};
###### onError
Após chamar *widget.load()*, o widget será carregado e inicializado. Qualquer erro fatal que ocorra depois disso ativará um callback opcional *onError*.
widget.onError = function (event) {
throw novo Erro(event.message);
};
###### onComplete
Assim que o jogo for concluído e o utilizador estiver na última tela. Também fornece um *data object* que descreve o que aconteceu no jogo.
*Nota: se quiser agir em relação a isto, poderá querer definir um tempo de espera dentro do callback para que o utilizador tenha tempo de ler a Tela Final, já que ocorre instantaneamente ao chegar na última tela. Também pode utilizar onClose.*
widget.onComplete = function (event) {
console.log(event.type); // “complete”
console.log(event.data); // {}
console.log("Pontuação do Utilizador foi" + event.data.gameMetrics.score);
};
###### onResize
Ocorre quando o Motor redimensiona, 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);
};
###### onFirstInteraction
Quando o utilizador interage (toque/clique) com a aplicação carregada pela primeira vez.
widget.onFirstInteraction = function () {
console.log("Utilizador interagiu com a Aplicação pela primeira vez");
};
###### onRouteChange
Ocorre quando a Aplicação muda de rota dentro do widget (navega entre telas). 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("Utilizador navegou para uma nova tela");
};
###### 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 seja ativada (CORS) ou precise 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 do utilizador quando ele completa 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 que este utilizador finaliza o jogo. |
###### Credenciais
| Chave | Descrição |
| ---- |
| **data.credentials.isPreviewMode** | Verifica se o jogo está no 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 detectar erros e recuperar informações sobre problemas que ocorrem dentro do widget:## onError Callback
O callback `onError` captura quaisquer erros fatais que ocorram após o widget ser carregado. Isto pode ser útil para identificar quando uma página não existe ou se ocorrer uma falha crítica.
widget.onError = function (event) {
if (typeof event.data.message !== 'undefined') {
switch (event.data.message) {
default:
// Não fazer nada
break;
case 'ERR_15':
console.log("Página não existe");
break;
}
}
};
## onRouteChange Callback
O callback `onRouteChange` é acionado quando a aplicação navega entre diferentes ecrãs dentro do widget. Isto é ú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) {
default:
// Não fazer nada
break;
case 'ERR_01':
console.log("Nenhum plano disponível");
break;
case 'ERR_02':
console.log("Conteúdo ainda não disponível");
break;
case 'ERR_03':
console.log("Conteúdo expirou");
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("ID da sessão não detetado");
break;
case 'ERR_10':
console.log("ID da sessão já utilizado");
break;
case 'ERR_11':
console.log("Plano não ativado");
break;
case 'ERR_12':
console.log("Dados incorretos recebidos");
break;
case 'ERR_13':
console.log("Chamada SSO falhou");
break;
case 'ERR_14':
console.log("Idioma indisponível");
break;
}
}
};
Ao utilizar tanto `onError` quanto `onRouteChange`, pode monitorizar e gerir eficazmente os problemas que possam ocorrer dentro do widget, garantindo uma melhor experiência de utilizador.
# Recuperando Informação do Utilizador na Tela Final (`onRouteChange`)
Ao usar **Dynamic Path™**, **Advent Calendar** ou **Combo™**, pode recuperar a informação do utilizador no final de qualquer jogo através do callback `onRouteChange`.
Este método é essencial porque o evento padrão `onComplete` só é acionado **uma vez que toda a experiência de múltiplas etapas esteja concluída**, e não quando cada jogo embutido termina.
Isto permite que o seu sistema receba os resultados completos do jogo (via `gameInfo`) quando o utilizador atinge a tela final da experiência.
# Configuração
Após criar o seu widget:
var widget = DigitaService.Widget.Create(options);
Adicione o listener `onRouteChange`:
widget.onRouteChange = function (event) {
console.log(event.type); // "routechange"
console.log(event.data); // { ... } ou undefined
console.log("Utilizador navegou para um novo ecrã");
};
# Detetando a Tela Final
Quando o utilizador atinge a tela final do jogo, o widget retornará uma rota correspondente:
event.data.screen === 'screen_end-YOUR_APP_ID'
Substitua `YOUR_APP_ID` pelo ID real da sua aplicação.# Obtenção da Informação do Utilizador (`gameInfo`)
Assim que a tela final for identificada, é possível extrair os dados:
event.data.gameInfo
`gameInfo` contém uma **lista de informação do utilizador**, que pode incluir:
* Dados de input do utilizador
* Resultados ou pontuações do jogo
* Campos recolhidos durante a experiência
Este conteúdo está disponível apenas na tela final para experiências utilizadas dentro de **Dynamic Path**, **Advent Calendar** ou **Combo**.
# Exemplo
widget.onRouteChange = function (event) {
if (event.data && event.data.screen === 'screen_end-12345') {
const dados = event.data.gameInfo;
console.log("Informação da tela final:", dados);
// Processar ou encaminhar esta informação conforme necessário
}
};
```
Actualizado em: 20/11/2025
Obrigado!