Weegloo Docs - Crear una app

Para subir al marketplace como Market App una aplicación web que usted mismo ha creado, primero debe compilar la app y preparar sus artefactos. Este proceso incluye compilar un sitio estático con HTML y JavaScript, y comprobar los artefactos de la compilación desde la línea de comandos.

Una Market App es una app que se sube al marketplace y se instala en otra Space. Su forma es la de una app web estática, igual que Web Hosting. Una vez subido el conjunto de archivos de pantalla compilado de antemano, cuando un visitante entra esas pantallas aparecen tal cual.

Hay una diferencia respecto a una app web normal, y por ella surge una regla que debe respetar al compilar. Esta página trata esa diferencia, esa regla y la verificación previa a la subida.

Al instalar, los recursos se copian a la Space de quien instala

Al instalar una Market App no solo se copia la pantalla de la app, sino que también los recursos seleccionados junto con ella en el momento de la publicación (Content Type, Content, Media, etc.) se copian a la Space de quien instala. Imagine que ha creado y subido una app de catálogo de productos para una tienda de ropa. Cuando alguien instala esa app, junto con la pantalla de la app, el Content Type de productos y el Content de productos se copian dentro de su Space.

Los recursos copiados reciben nuevos identificadores en la Space donde se instalan. El Delivery Access Token que se usa para leer el contenido también se crea de nuevo en la Space donde se instala. Por eso la app instalada no lee la Space del creador, sino su propia copia copiada en la Space de quien instala. Una vez terminada la instalación, esa app funciona solo con los recursos de la Space donde se instaló.

Por qué la información de acceso queda incrustada en la compilación

Una Market App instalada no tiene servidor. Al ser hosting estático, igual que Web Hosting, no hay un runtime de servidor que calcule la pantalla en cada petición, y el contenido lo obtiene directamente el navegador llamando a la API de entrega de WEEGLOO (CDA, Content Delivery API). Por eso, dentro de los artefactos de la compilación (los archivos de pantalla) debe estar escrito en qué Space leer qué, y con qué credencial.

El problema es que, como se ha visto antes, al instalar los recursos se copian con nuevos identificadores. Los valores escritos en los archivos de la compilación son el identificador y el token de la Space del creador, pero lo que hay que leer en el lugar de instalación es la copia recién creada. Si se dejan los valores antiguos tal cual, la app apunta a un sitio equivocado.

Por eso WEEGLOO sustituye estos valores en su lugar al instalar. En el momento de la publicación localiza de antemano dónde están escritos, dentro del texto de la compilación, el identificador, el token y los identificadores de recurso de la Space del creador, y al instalar reemplaza ese lugar por los nuevos valores de la copia de la Space donde se instala. Gracias a ello, la app instalada apunta automáticamente a la Space donde se instaló.

Esta sustitución ocurre solo sobre los recursos incluidos junto con la app. Por eso, los recursos que la pantalla lee (Content Type, Delivery Access Token, etc.) deben incluirse todos en el momento de la publicación. Si se omite alguno, ese identificador no se sustituye y queda con un valor equivocado en el lugar de instalación. Qué hay que incluir se trata en la selección de recursos de Publicar la app.

Esta sustitución automática tiene una condición previa: que el valor figure dentro del texto de la compilación tal cual, como una única cadena íntegra. Esto se debe a que la fase de publicación busca esa cadena al pie de la letra y registra su posición. Si parte el valor, lo construye durante la ejecución o lo hace recibir desde fuera, la fase de publicación no lo encuentra; y entonces, al instalar, tampoco ocurre la sustitución, y la app instalada no funciona.

Los valores que se incrustan en la compilación (y que se sustituyen al instalar) son tres.

El sys.id de la Space original (spaceId): en qué Space leer.
El Delivery Access Token de la Space original: la credencial de solo lectura que permite leer el contenido publicado de esa Space.
El sys.id de los recursos a los que la app hace referencia: por ejemplo, el sys.id del Content Type que contiene los productos, es decir, los identificadores de recurso a los que apunta el código del cliente.

Incrustar los valores como literales

La clave es que esos tres valores deben aparecer dentro de los artefactos de la compilación como una única cadena literal íntegra (intact literal substring). Al abrir el archivo de texto compilado (JS, HTML, JSON, etc.), el valor debe verse de una sola pieza, sin partirse ni transformarse. Solo así la fase de publicación puede encontrar ese valor y registrar su posición, y la fase de instalación puede reemplazar ese lugar por el nuevo valor.

A continuación se muestra un ejemplo de configuración puesta en el código del cliente. Los valores solo muestran el formato a modo de ejemplo, y debe sustituirlos por sus credenciales reales.

// weegloo.config.js: estos valores se incluyen tal cual en los artefactos de la compilación
export const WEEGLOO = {
  spaceId: "spc_xxxxxxxxxxxxxxxx",                 // sys.id de la Space original
  deliveryAccessToken: "dat_xxxxxxxxxxxxxxxxxxxx",  // Delivery Access Token de la Space original
  productContentTypeId: "ct_xxxxxxxxxxxx",          // sys.id del Content Type que la app lee
};

El navegador llama a CDA directamente con estos valores.

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

Las siguientes formas no se deben usar. Todas hacen que el valor no quede como un literal íntegro en los artefactos de la compilación, e impiden que la fase de publicación lo encuentre. Entonces, al instalar no ocurre la sustitución, y la app instalada no puede leer la copia de su propia Space.

Consultar variables de entorno en tiempo de ejecución. La app instalada no tiene servidor ni entorno de ejecución que inyecte el valor, y este tampoco queda escrito en el texto de la compilación.
```
// No válido: esta variable de entorno no existe en el lugar de instalación
deliveryAccessToken: process.env.DELIVERY_ACCESS_TOKEN
```
Obtenerlo mediante un fetch en tiempo de ejecución. Si hace que el valor se reciba desde algún sitio, este no queda en el texto de la compilación y tampoco hay un lugar de donde recibirlo.

Partirlo mediante concatenación de cadenas. El valor no aparece de una sola pieza y la fase de publicación no lo encuentra.

// No válido: en los artefactos, "dat_xxxxxxxxxxxxxxxxxxxx" no queda como una sola substring
deliveryAccessToken: "dat_" + "xxxxxxxxxxxxxxxxxxxx"

Dejarlo como marcador de posición o en blanco. Rellenar el valor es algo que hace WEEGLOO al instalar. Pero esa sustitución consiste en encontrar el valor real incrustado en la compilación y reemplazar ese lugar, así que, si lo deja en blanco o con una marca temporal, no hay ningún valor que encontrar y no puede ser objeto de la sustitución. En el momento de generar los artefactos de la compilación, el valor real debe estar dentro al pie de la letra.

Ponga siempre los valores en un archivo de texto (JS, HTML, JSON, etc.). No los ponga en archivos binarios como imágenes o tipografías. La tarea de buscar y reemplazar valores solo ocurre en archivos de texto.

El empaquetador (bundler) también es objeto de comprobación. Algunos empaquetadores parten o transforman las cadenas literales durante la optimización. No se confíe mirando solo el código fuente: abra los artefactos reales de la compilación y compruebe si el valor permanece como un literal íntegro (siguiente apartado).

Emita el token con el mínimo privilegio

El Delivery Access Token que incrusta en la compilación queda expuesto tal cual en el navegador. Cualquiera que instale puede ver este valor en los archivos de la compilación de la app (y el token que se crea de nuevo en esa Space tras la instalación también queda expuesto del mismo modo). Por lo tanto, este token debe emitirse con un SpaceRole de mínimo privilegio que solo pueda leer los Content Type que la app realmente necesita leer. No lo emita con el rol Administrator. Si un token con privilegios de administrador queda expuesto en el navegador, toda la Space original queda en riesgo.

Cómo crear un SpaceRole de mínimo privilegio y emitir el Delivery Access Token con ese rol se trata en Token.

Verificación previa a la publicación

Antes de subir, compruebe en los artefactos reales de la compilación, y no de memoria, que los valores se han incluido correctamente. En la carpeta compilada, haga grep por separado del spaceId original, el token y el sys.id de cada recurso, y vea si aparecen como literales íntegros.

grep -r "DATxxxxxxxxxxxxxxxx" dist/

Basta con que el valor buscado aparezca de una sola pieza (sin partirse ni transformarse) dentro de los artefactos de la compilación. Compruébelo para los tres valores incrustados (spaceId, Delivery Access Token y el sys.id del recurso referenciado). Si alguno no aparece en el grep, la fase de publicación tampoco lo encontrará y no se sustituirá al instalar (el empaquetador habrá transformado el valor, o se habrá perdido por una consulta en tiempo de ejecución). En ese caso, consulte el apartado anterior "Incrustar los valores como literales" y corríjalo para que el valor permanezca como un literal íntegro.

Restricciones de la compilación estática

Los artefactos de la compilación de una Market App siguen las mismas restricciones estáticas que Web Hosting.

No hay runtime de servidor. Debe compilarse como export estático (sin SSR).
Al descomprimir, debe haber 100 archivos o menos.
En la parte más alta (la raíz) del conjunto debe haber un index.html.
Las llamadas a las API de WEEGLOO (CDA, etc.) se hacen directamente desde el navegador.

Las restricciones estáticas detalladas y las reglas del conjunto de archivos se tratan en Publicación de sitios web.

Las pantallas compiladas se incluyen en el App Bundle

Los artefactos de la compilación ya verificados se incluyen, al publicar, en un App Bundle (un paquete que agrupa la app por versiones). Los recursos seleccionados junto a ella en la pantalla de publicación también se incluyen en el mismo paquete y, al instalar, se copian a la Space de quien instala. El procedimiento para publicar y subir de versión se trata en Publicar la app.

Si la app admite sus propios miembros

Hasta aquí se ha tratado el caso en que se lee con CDA contenido público que cualquiera puede leer. Si la app admite su propio registro e inicio de sesión de miembros, se usa ServiceLogin y el SDK oficial de cliente. En ese caso el navegador no llama a CDA, sino a ACDA (App Content Delivery API) con el token del miembro. La configuración y el método de integración se tratan en Inicio de sesión de miembros del servicio.

El método de autenticación de una Market App instalada lo trata App Auth, y los usuarios con permiso de acceso a la app instalada los trata App Member.

Qué hacer a continuación

Publicar la app: trata el procedimiento de estudio de contenidos para subir al marketplace la app creada (App Bundle).
Publicación de sitios web: trata los aspectos básicos de Web Hosting, como la compilación estática, el límite de 100 archivos o el index.html en la raíz.
Token: trata cómo emitir, con un SpaceRole de mínimo privilegio, el Delivery Access Token que se incrusta en la compilación.
Referencia de la API: trata las especificaciones técnicas, como el formato de petición de CDA (la API de entrega) que las pantallas de la app llaman al cargar el contenido, y de ACDA si la app admite sus propios miembros.