Manifiesto de instalación

Introducción

De aquí en adelante a los addon les llamaremos complemento. En algunos navegadores Mozilla, dependiendo del idioma español descargado para traducir la interfaz del navegador, se leerá como agregado en Herramientas->Agregado.

Un manifiesto de instalador es un archivo agregado que la aplicación XUL (Administrador-Habilitado) usa para determinar la información acerca de como un agregado ó complemento (Add-on) ha de ser instalado. Este archivo contiene metadatos que identifican el complemento/agregado, provee información del creador de éste, donde se puede hallar más información acerca del complemento/agregado, con cuales versiones de qué aplicaciones es compatible, como debería ser actualizado y cosas por el estilo.

El formato de un mainfiesto de instalador es RDF/XML.

El archivo debe ser llamado install.rdf y ubicarse en el nivel superior del archivo XPI de un complemento.

Disposición

La disposición básica de un manifiesto de instalador es algo como esto:

<?xml version="1.0"?>

<RDF xmlns="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="https://www.mozilla.org/2004/em-rdf#">
  <Description about="urn:mozilla:install-manifest">
    <!-- properties -->
  </Description>
</RDF>

Algunas propiedades son requeridas, otras son opcionales; algunas tienen cadenas simples, otras son recursos complejos.

Referencia de propiedades requeridas

Su manifiesto de instalador debe especificar estas propiedades correctamente, de lo contrario su agregado/complemento podría no instalarse.

id

La id de la extension, la cual es un:

• GUID (generada usando guidgen en Windows, uuidgen en Linux and makeuuid en Solaris) (Firefox 1.0)
• Firefox 1.5 y superiores: Una cadena con fomato del tipo: [email protected]

Este último formato es significativamente más fácil de generar y manipular. Firefox 1.5 tiene una comprobación para asegurarse que su id caiga dentro de un formato u otro y rechazará la instalació de complemetos/agregados que tengan ids mal formadas.

Ejemplos

<em:id>[email protected]</em:id>

<em:id>{daf44bf7-a45e-4450-979c-91cf07434c3d}</em:id>

versión

La cadena de versión identificando la versión del complemento que está siendo proveído.

Para Firefox/Thunderbird 1.0, el formato debe cumplir las reglas especificadas en Extensión de versiones, Actualización y Compatibilidad. Para Firefox/Thunderbird 1.5, ver Herramientas para formato de versión.

Ejemplos

<em:version>2.0</em:version>

<em:version>1.0.2</em:version>

<em:version>0.4.1.2005090112</em:version>

Firefox 1.5 / XULRunner 1.8 - Complementos/agregados que no usan un formato de versión válido no serán instalados. El formato de la versión es diferente a, pero compatible con, 1.0's.

Para complementos alojados en addons.mozilla.org - La actualización del sitio web de Mozilla puede reinstalar su complemento/agregado y corregir o rechazar versiones con cadenas de versión malformadas.

tipo

Un valor de tipo entero representa el tipo de complemento/agregado.

Ejemplos

<em:type>2</em:type>

Nuevo en Firefox 1.5 Esta propiedad fue añadida para Firefox 1.5, y es requerida únicamente para otros tipos de complementos/agregados diferentes a Extensiones y Temas.

Aplicación destino (targetApplication)

Un objeto que especifica una aplicación a la cual se dirije este complemento. Esto significa que el complemento trabajará con la aplicación definida por la propiedad id (<em:id>) especificada (para una lista compensiva de IDs de aplicaciones y sus valores máximo y mínimo (min/maxVersions) véase "Versiones de aplicaciones válidas para Desarrolladores de complementos/agregados", desde la versión mínima (<em:minVersion>) hasta e incluyendo la versión máxima (<em:maxVersion>). Estas cadenas para versión tienen el mismo formato que la propiedad de versión y será comparada con la versión de la aplicación; esto permite al autor de la extensión especificar, cuáles extensiones y con qué versiones de Firefox han sido probadas.

Nota: Las extensiones compatibles con Firefox 3.5 deberán especificar un maxVersion de 3.5 *, por lo que son compatibles con actualizacinoes de seguridad de estabilidad. Para Firefox 3.0, debiera usarse un maxVersion de 3.0.* Las extensiones compatibles únicamente con Firefox o Thunderbird 2.0 deberán especificar un maxVersion de 2.0.0*.

El manifiesto de instalador debe especificar al menos uno de estos objetos y podría especificar más si el complemento/agregado tiene múltiples aplicaciones destino que soportan al Administrador del complemento/agregado. (por ejemplo Firefox y Thunderbird).

Ejemplos

<em:targetApplication>
 <Description>
  <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id> Firefox
  <em:minVersion>1.5</em:minVersion>
  <em:maxVersion>2.0.0.*</em:maxVersion>
 </Description>
</em:targetApplication>

Nuevo en Firefox 3 Las aplicaciones basadas en Gecko 1.9 te permiten usar la id especial targetApplication id [email protected] para indicar que el complemento/agregado es compatible con cualquier aplicación tipo toolkit que tenga valores similares de minVersion y maxVersion.

nombre (name)

El nombre del complemento, previsto para mostrarlo en el interfaz de usuario (UI = User Interface).

Ejemplos

<em:name>Mi Extension</em:name>

Referencia de propiedades opcionales

Podrías necesitar proveer estas propiedades, dependiendo de las capacidades de tu complemento/agregado.

localizado (localized)

Nuevo en Firefox 3 Te permite localizar el nombre de tu complemento/agregado, descripción, contribuidores y otros metadatos. La descripción de localized debe especificar al menos un em:locale que indique cuáles locales usan esta información.

Ejemplos

Esto declara un set de metadatos de un complemento/agregado para mostrar en pantalla cuando la aplicación se está ejecutando en el local de-DE.

<em:localized>
  <Description>
    <em:locale>de-DE</em:locale>
    <em:name>Tab Sidebar</em:name>
    <em:description>Zeigt in einer Sidebar Vorschaubilder der Inhalte aller offenen Tabs an.</em:description>
  </Description>
</em:localized>

Las siguientes propiedades que son descritas en otra parte en ésta página pueden ser incluidas en la propiedad localized:

• name (nombre)
• description (descripción)
• creator (creador)
• homepageURL (URL de la página de inicio)
• developer (desarrollador)
• translator (traductor)
• contributor (contribuidor)

Más documentos pueden hallarse en Localización de descripción para extensiones.

descripción (description)

Una corta descripción del complemento/agregado - Prevista para mostrar en la interfaz de usuario. Esta descripción debe encajar en una corta linea de texto..

Ejemplos

<em:description>Herramienta Avanzada foo.</em:description>

creator

El nombre del creador/desarrollador principal - Prevista para mostrar en la interfaz de usuario.

Ejemplos

<em:creator>John Doe</em:creator>

ó

<em:creator>El Equipo Extensión </em:creator>

developer

Nuevo en Firefox 2 El/los nombre(s) de co-desarrolladores. Se deben especificar mas de uno de estos valores para especificar múltiples desarrolladores.

Ejemplos

<em:developer>Jane Doe</em:developer>
<em:developer>Koos van der Merwe</em:developer>

translator

Nuevo en Firefox 2 El/los nombre(s) de traductores. Se deben especificar mas de uno de estos valores para especificar múltiples traductores.

Ejemplos

<em:translator>Janez Novak</em:translator>
<em:translator>Kari Nordmann</em:translator>

contributor

El/los nombre(s) de contribuidores adicionales. Se deben especificar mas de uno de estos valores para especificar múltiples contribuidores.

Ejemplos

<em:contributor>John Doe</em:contributor>

<em:contributor>John Doe</em:contributor>
<em:contributor>Jane Doe</em:contributor>
<em:contributor>Elvis Presley</em:contributor>

homepageURL

Un enlace a la página inicio del complemento/agregado - Prevista para mostrar en la interfaz de usuario.

Ejemplos

<em:homepageURL>https://www.foo.com/</em:homepageURL>

updateURL

Es un enlace a un archivo de manifiesto para actualización personalizada que especifica la disponibilidad de actualizaciones para el complemento/agregado. El fomato se describe abajo. Si está activado el administrador del complemento/agregado periódicamente verificará con este archivo de manifiesto si hay disponibles versiones más recientes.

Nuevo en Firefox 3 Por razones de seguridad, las aplicaciones en Gecko 1.9 requieren que si al especificar una updateURL, esta debe ser un URL tipo https, o deberás incluir un updateKey.

Su servidor debe enviar este archivo como text/rdf, text/xml ó aplicación/xml+rdf; o el analizador de actualizaciones no funcionará. 

El administrador de complementos/agregados reemplazará los siguientes valores dentro de la URL en caso que desees generar la respuesta RDF dinámicamente, por ejemplo al usar PHP o CGI:

Ejemplos

<em:updateURL>https://www.foo.com/update.cgi?id=%ITEM_ID%&amp;version=%ITEM_VERSION%</em:updateURL>
<em:updateURL>https://www.foo.com/extension/windows.rdf</em:updateURL>

Para complementos/agregados alojados en addons.mozilla.org: No debe una propiedad updateURL. Por defecto, las aplicaciones Mozilla que usan el administrador de complementos/agregados (tales como Firefox y Thunderbird) enviarán peticiones de actualización a addons.mozilla.org usando el servicio web predeterminado. Cada vez que usted suba o publique una nueva versión de su complemento/agregado, o cambie los parámetros de compatibilidad mediante la interfaz de autor, su manifiesto de actualización será generado automáticamente.

Formato del manifiesto de actualización: El manifiesto de actualización es una fuente de datos RDF/XML. Para ejemplos de un manifiesto de actualización, véase Versiones de Extensión, Actualización y Compatibilidad y Habilitación de actualización de extensiones (externas).

Clave de actualización (updateKey)

Para mantener la seguridad de las actualizaciones de los datos rdf que son recuperados de http plan debes usa firmas digitales para verificar el contenido de los datos. Con este fin debes incluir la parte pública de la clave criptográfica en una entrada de updateKey en el archivo install.rdf del complemento/agregado. Esta puede generarse usando la herramienta McCoy. Cualquier linea descontinuada y espacio en blanco como parte de esta entrada será ignorada.

Ejemplos

 <em:updateKey>MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDK426erD/H3XtsjvaB5+PJqbhj
               Zc9EDI5OCJS8R3FIObJ9ZHJK1TXeaE7JWqt9WUmBWTEFvwS+FI9vWu8058N9CHhD
               NyeP6i4LuUYjTURnn7Yw/IgzyIJ2oKsYa32RuxAyteqAWqPT/J63wBixIeCxmysf
               awB/zH4KaPiY3vnrzQIDAQAB</em:updateKey>

optionsURL

La chrome:// URL del cuadro de diálogo de opciones de la extensión. Es útil únicamente para extensiones. Si esta propiedad es especificada, cuando la extensión es seleccionada en la lista de extensiones, el botón de opción está habilitado y mostrará esto:

Ejemplos

<em:optionsURL>chrome://miext/content/options.xul</em:optionsURL>

aboutURL

La chrome:// URL del cuadro de diálogo acerca de la extensión, Es útil únicamente para extensiones. Si esta propiedad es especificada, cuando la extensión es seleccionada en la lista de extensiones, el enlace acerca de... en el menú contextual del complemento/agregado mostrará este diálogo, mas bien por defecto.

Ejemplos

<em:aboutURL>chrome://myext/content/about.xul</em:aboutURL>

iconURL

Un chrome:// URL de icono 32x32 para mostrar en la lista de complementos/agregados. Si esta propiedad no es especificada, se usará un icono por defecto.

<em:iconURL>chrome://miext/skin/icon.png</em:iconURL>

hidden

Valor booleano que cuando es true (verdadero) provoca que el complemento/agregado no se muestre en la lista de complementos/agregados, cuando es proveído el complemento/agregado se instalará en el Area de Acceso Restringido (entonces no trabaja como un complemento/agregado instalado en el perfil). Esto es para la integración de grandes aplicaciones donde no tiene sentido tener una lista de aplicaciones.

Ejemplos

<em:hidden>true</em:hidden>

targetPlatform

Nuevo en Firefox 1.5 Una cadena que especifica la plataforma que el complemento/agregado soporta. Contiene uno u otro de los valores de OS_TARGET solo ó combinado con TARGET_XPCOM_ABI, separados por un guión bajo (_).

Puedes especificar propiedades para múltiples targetPlatform por manifiesto. Si algún valor concuerda con los parámetros de construcción de la aplicación, será instalado; si no, el usuario recibira un apropiado mensaje de error.

Ejemplos

<em:targetPlatform>WINNT_x86-msvc</em:targetPlatform>

<em:targetPlatform>Linux</em:targetPlatform>

<em:targetPlatform>Darwin_ppc-gcc3</em:targetPlatform>

<em:targetPlatform>SunOS_sparc-sunc</em:targetPlatform>

Usualmente, usarías únicamente la parte OS para temas o para extensiones que no son totalmente para plataforma cruzada. Para extensiones que incluyen componentes binarios (compilados), nunca deberá usar el OS solo, sino incluir el ABI (s) con el cual compilaste los componentes. Si deseas incluir múltiples versiones de los componentes, deberías también usar Subdirectorios de Plataforma-específica.

Notas

• En el mismo archivo de manifiesto, podrías incluso mezclar valores con y sin ABI. Si un valor para el OS (sistema operativo) de la aplicación encuentra que requiere algún ABI específico, el ABI se considera importante para el sistema operativo y la aplicación rechazará la instalación del complemento/agregado si no encuentra relación en la combinación OS/ABI. Esto significa que si todos los ejemplos anteriores pudieran ocurrir en un solo manifiesto, el complemento/agregado se instalará en cualquier versión linux de la aplicación, a pesar de su ABI, pero no en una versión Windows Cygwin.
• Quizás encuentres versiones de Firefox y Thunderbird para las que desconozcas sus ABI (la mayoría puertos hacia plataformas raras ó versiones no oficiales). Estas versiones rechazarán instalar cualquier complemento/agregado que requiera un ABI específico para sus plataformas.

Esta propiedad fué agregada para el Firefox/Thunderbird 1.5. Las versiones previas de estas aplicaciones ignorarán las restricciones e instalarán el complemento/agregado a pesar de la plataforma.

requires

Nuevo en Firefox 2 Este apartado tiene una sintaxis similar a la de <em:targetApplication>. Si el complemento/agregado especificado por el apartado <em:id> no es instalado o tienes una versión incompatible, el administrador de extensiones deshabilitará tu extensión y mostrará el mensaje "Requiere items adicionales". Puedes poner tantos apartados <em:requires> como quieras. Tu extensión será deshabilitada si cualquiera de los requisito especificados falla.

Ejemplo

<em:requires>
   <Description>
     <!-- Lightning -->
     <em:id>{e2fda1a4-762b-4020-b5ad-a41df1933103}</em:id>
     <em:minVersion>0.5pre</em:minVersion>
     <em:maxVersion>0.5pre</em:maxVersion>
   </Description>
 </em:requires>

Notas

• Actualmente, únicamente <em:id>, <em:minVersion>, <em:maxVersion> son analizadas dentro del apartado <em:requires>.
• No es posible actualmente agregar dependencias que sean especificas para un <em:targetApplication>. Véase wikimo:Administrador de Extensiones: Dependencias de Extensiones para más detalles.

Esta propiedad fué agregada para Firefox/Thunderbird 2. Versiones previas de estas aplicaciones ignorarán las restricciones e instalarán el complemento/agregado a pesar de los requisitos.

Referencia de propiedades obsoletas

Estas propiedades eran requeridas en viejas versiones del administrador de complementos/agregados, pero han sido reemplazadas por nuevos y mejores mecanismos.

file

Firefox 1.0 Esta propiedad apunta a un archivo chrome .jar que contiene paquetes chrome que requieren ser registrados con el registro de chrome.

La propiedad <em:file> tiene un complejo valor de objeto. El uri(Uniform Resource Identifier - Identificador Uniforme de Recurso) del valor es urn:mozilla:extension:file:jarFile.jar donde jarFile.jar es el nombre del archivo jar que contiene el paquete de archivos de chrome. Este podría ser también el nombre de un directorio que contiene los archivos del paquete chrome, des-jareado (e.g. urn:mozilla:extension:file:directory). En todo caso, el referido paquete de archivos chrome debe estar ubicado en el subdirectorio chrome de los XPI.

Este objeto tiene una propiedad package (con una ruta dentro del archivo jar o del directorio que lleva a la ubicación del archivo contents.rdf que es el responsable del registro del paquete), una propiedad locale (ídem, pero registra el locale) y una propiedad skin (ídem, pero para registrar el material del tema).

En extensiones para Firefox 1.5, esta propiedad ya no es necesaria: el chrome.manifest en el nivel más alto del XPI es usado para ubicar el chrome a registrar. Si no hay chrome.manifest, esta propiedad es aún leída por el administrador de complementos/agregados y un chrome.manifest es generado a partir del antiguo archivo contents.rdf.

Ejemplos

<em:file>
 <Description about="urn:mozilla:extension:file:myext.jar">
  <em:package>content/myext/</em:package>
  <em:locale>locale/en-US/myext/</em:locale>
  <em:skin>skin/classic/myext/<em:skin>
 </Description>
</em:file>

Un manifiesto de instalador puede especificar múltiples propiedades file; una para cada archivo jar o subdirectorio que contenga el chrome a registrar.

Glosario

Acceso de área restringida

Un Area de Acceso Restringido es una ubicación para instalar que puede estar restringida en una cuenta de acceso-restringido, no importando si la ubicación está restringida aún con los privilegios del usuario actual.  (véase nsIInstallLocation::restricted ). Actualmente, la carpeta $APPDIR)/extensions y la ubicación del registro de instalación bajo HKEY_LOCAL_MACHINE (véase Agregando Extensiones usando el Registro de Windows (para detalles) están restringidas.

Las ubicaciones de instalación ($PROFILE)/extensions y HKEY_CURRENT_USER, por otro lado no están restringidas.