Weegloo Docs - Criação do aplicativo

Para enviar um aplicativo web que você mesmo criou ao marketplace como um Market App, primeiro é preciso compilar o aplicativo e preparar seus artefatos. Esse processo envolve compilar um site estático em HTML e JavaScript e verificar os artefatos da compilação na linha de comando.

Um Market App é um aplicativo que você envia ao marketplace para ser instalado em outro Space. Em formato, é um aplicativo web estático igual ao Web Hosting. Quando você envia um conjunto de arquivos de tela compilados de antemão, essas telas aparecem tal como estão quando um visitante acessa.

Há uma diferença em relação a um aplicativo web comum, e por causa dela surge uma regra que você deve seguir ao compilar. Esta página trata dessa diferença, dessa regra e da verificação antes do envio.

Ao instalar, os recursos são copiados para o Space de quem instala

Quando um Market App é instalado, além das telas do aplicativo, os recursos selecionados junto na publicação (Content Type, Content, Media etc.) também são copiados para o Space de quem instala. Imagine que você criou e enviou um aplicativo de catálogo de produtos de uma loja de roupas. Quando alguém instala esse aplicativo, junto com as telas do aplicativo, o Content Type de produto e o Content de produto são copiados para o Space dessa pessoa.

Os recursos copiados recebem novos identificadores no Space onde foram instalados. O Delivery Access Token usado para ler o conteúdo também é criado de novo no Space da instalação. Por isso, o aplicativo instalado não lê o Space do criador, mas sim a sua própria cópia copiada para o Space de quem instalou. Assim que a instalação termina, esse aplicativo funciona apenas com os recursos do Space da instalação.

Por que as informações de acesso ficam embutidas na compilação

Um Market App instalado não tem servidor. Como é uma hospedagem estática igual ao Web Hosting, não há um servidor em tempo de execução que calcule a tela a cada requisição, e o próprio navegador chama a API de entrega da WEEGLOO (CDA, Content Delivery API) diretamente para buscar o conteúdo. Por isso, dentro dos artefatos da compilação (os arquivos de tela) deve estar escrito de qual Space ler o quê e com qual credencial.

O problema é que, como visto acima, ao instalar os recursos são copiados com novos identificadores. Os valores escritos no arquivo de compilação são os identificadores e tokens do Space do criador, mas o que precisa ser lido no local da instalação é a cópia recém-criada. Se você deixar os valores antigos, o aplicativo apontará para o lugar errado.

Por isso, a WEEGLOO substitui esses valores por você no momento da instalação. Na publicação, ela localiza de antemão onde estão escritos os identificadores, tokens e identificadores de recursos do Space do criador dentro do texto da compilação, e na instalação substitui esses lugares pelos novos valores da cópia do Space de quem instalou. Graças a isso, o aplicativo instalado passa a apontar automaticamente para o Space da instalação.

Essa substituição acontece apenas para os recursos incluídos junto com o aplicativo. Portanto, os recursos que as telas leem (Content Type, Delivery Access Token etc.) devem ser incluídos sem falta na publicação. Se você esquecer algum, esse identificador não será substituído e permanecerá com um valor errado no local da instalação. O que deve ser incluído junto é tratado na seleção de recursos em Publicação do aplicativo.

Essa substituição automática tem uma condição. O valor deve estar dentro do texto da compilação como uma única cadeia íntegra, tal como está. Isso porque a etapa de publicação procura essa cadeia literalmente e registra sua posição. Se você dividir o valor, gerá-lo durante a execução ou recebê-lo de fora, a etapa de publicação não o encontrará e, assim, a substituição não ocorrerá na instalação, deixando o aplicativo instalado sem funcionar.

São três os valores embutidos na compilação (e substituídos na instalação).

O sys.id do Space original (spaceId): de qual Space ler.
O Delivery Access Token do Space original: a credencial somente leitura que permite ler o conteúdo publicado desse Space.
O sys.id dos recursos referenciados pelo aplicativo: por exemplo, o sys.id do Content Type que contém os produtos, ou seja, os identificadores de recursos para os quais o código do cliente aponta.

Inserir os valores como literais inline

O ponto central é que os três valores acima devem aparecer dentro dos artefatos da compilação como uma única cadeia literal íntegra (intact literal substring). Quando você abre o arquivo de texto compilado (JS, HTML, JSON etc.), o valor deve aparecer como um único bloco, sem ter sido dividido ou alterado. Só assim a etapa de publicação consegue encontrar esse valor e registrar sua posição, e a etapa de instalação consegue substituir esse lugar pelo novo valor.

Abaixo está um exemplo de configuração colocada no código do cliente. Os valores apenas demonstram o formato; você deve substituí-los pelas credenciais reais.

// weegloo.config.js: estes valores ficam embutidos tal como estão nos artefatos da compilação
export const WEEGLOO = {
  spaceId: "spc_xxxxxxxxxxxxxxxx",                 // sys.id do Space original
  deliveryAccessToken: "dat_xxxxxxxxxxxxxxxxxxxx",  // Delivery Access Token do Space original
  productContentTypeId: "ct_xxxxxxxxxxxx",          // sys.id do Content Type que o aplicativo lê
};

O navegador chama o CDA diretamente com esses valores.

fetch(`https://cda.weegloo.com/v1/spaces/${WEEGLOO.spaceId}/contents`, {
  headers: { Authorization: `Bearer ${WEEGLOO.deliveryAccessToken}` },
});

As abordagens a seguir não devem ser usadas. Todas fazem com que o valor não permaneça como um literal íntegro nos artefatos da compilação, impedindo que a etapa de publicação encontre o valor. Nesse caso, a substituição não ocorre na instalação e o aplicativo instalado não consegue ler a cópia do seu próprio Space.

Consulta de variável de ambiente em tempo de execução. O aplicativo instalado não tem um servidor ou ambiente de execução para injetar o valor, e o valor também não fica registrado como texto na compilação.
```
// Não funciona: esta variável de ambiente não existe no local da instalação
deliveryAccessToken: process.env.DELIVERY_ACCESS_TOKEN
```
Buscar via fetch em tempo de execução. Se você fizer o valor ser recebido de algum lugar, ele não permanece no texto da compilação e também não há de onde recebê-lo.

Dividir por concatenação de cadeias. O valor não aparece como um único bloco, então a etapa de publicação não o encontra.

// Não funciona: "dat_xxxxxxxxxxxxxxxxxxxx" não permanece como uma única substring no artefato
deliveryAccessToken: "dat_" + "xxxxxxxxxxxxxxxxxxxx"

Deixar como placeholder ou em branco. Preencher o valor é tarefa que a WEEGLOO faz na instalação. Mas essa substituição consiste em encontrar o valor real embutido na compilação e trocar aquele lugar; se você deixar em branco ou com uma marcação temporária, não há valor a ser encontrado e ele não se torna alvo de substituição. No momento em que os artefatos da compilação são gerados, o valor real deve estar presente literalmente como texto.

Coloque os valores sempre em arquivos de texto (JS, HTML, JSON etc.). Não os coloque em arquivos binários como imagens ou fontes. A operação de encontrar e substituir o valor ocorre somente em arquivos de texto.

O bundler também é algo a verificar. Alguns bundlers dividem ou alteram cadeias literais durante a otimização. Não se sinta seguro olhando apenas o código-fonte: abra os artefatos reais da compilação e verifique se o valor permanece como um literal íntegro (próxima seção).

Emita o token com o mínimo de privilégios

O Delivery Access Token embutido na compilação fica exposto diretamente no navegador. Qualquer pessoa que instale pode ver esse valor nos arquivos de compilação do aplicativo (o token recriado nesse Space após a instalação também fica exposto da mesma forma). Por isso, esse token deve ser emitido com um SpaceRole de mínimo privilégio que só consiga ler os Content Type que o aplicativo realmente precisa ler. Não emita com o papel Administrator. Se um token com privilégios de administrador for exposto no navegador, todo o Space original fica em risco.

A forma de criar um SpaceRole de mínimo privilégio e emitir um Delivery Access Token com esse papel é tratada em Token.

Verificação antes da publicação

Antes de enviar, verifique se os valores foram inseridos corretamente nos artefatos reais da compilação, e não de cabeça. Na pasta compilada, faça grep do spaceId original, do token e do sys.id do recurso, cada um, e veja se aparecem como um literal íntegro.

grep -r "DATxxxxxxxxxxxxxxxx" dist/

Basta que o valor procurado apareça como um único bloco (sem ter sido dividido ou alterado) dentro dos artefatos da compilação. Verifique todos os três valores embutidos (spaceId, Delivery Access Token e o sys.id do recurso referenciado). Se algum deles não for capturado pelo grep, a etapa de publicação também não o encontrará e ele não será substituído na instalação (o bundler alterou o valor ou ele foi excluído por uma consulta em tempo de execução). Nesse caso, consulte a seção anterior "Inserir os valores como literais inline" e corrija para que o valor permaneça como um literal íntegro.

Restrições da compilação estática

Os artefatos da compilação de um Market App seguem as mesmas restrições estáticas do Web Hosting.

Não há servidor em tempo de execução. Você deve compilar com export estático (sem SSR).
Ao descompactar, deve haver 100 arquivos ou menos.
Deve haver um index.html no topo (raiz) do conjunto.
As chamadas às APIs da WEEGLOO (CDA etc.) são feitas diretamente do navegador.

As restrições estáticas detalhadas e as regras do conjunto de arquivos são tratadas em Implantação de sites.

As telas compiladas vão para o App Bundle

Os artefatos da compilação já verificados vão, na publicação, para o App Bundle (o pacote que agrupa o aplicativo por versão). Os recursos selecionados junto na tela de publicação também ficam no mesmo pacote e são copiados para o Space de quem instala na instalação. O procedimento de publicar e subir a versão é tratado em Publicação do aplicativo.

Se o aplicativo recebe membros próprios

Até aqui consideramos o caso de ler, via CDA, conteúdo público que qualquer pessoa pode ler. Se o aplicativo receber cadastro e login de membros próprios, ele usa o ServiceLogin e o SDK cliente oficial. Nesse caso, o navegador chama a ACDA (App Content Delivery API), e não o CDA, com o token do membro. A configuração e a forma de integração são tratadas em Login de membros do serviço.

O modo de autenticação de um Market App instalado é tratado por App Auth, e os usuários com permissão de acesso ao aplicativo instalado são tratados por App Member.

O que fazer a seguir

Publicação do aplicativo: trata do procedimento no estúdio de conteúdo para enviar ao marketplace o aplicativo criado (App Bundle).
Implantação de sites: trata dos fundamentos do Web Hosting, como a compilação estática, o limite de 100 arquivos e o index.html na raiz.
Token: trata de como emitir o Delivery Access Token a ser inserido inline na compilação com um SpaceRole de mínimo privilégio.
Referência da API: trata das especificações técnicas, como o formato de requisição do CDA (API de entrega) que as telas do aplicativo chamam ao carregar o conteúdo, e da ACDA caso o aplicativo receba membros próprios.