La versión 1 del manifiesto dejó de estar disponible en Chrome 18 y se eliminará la compatibilidad gradualmente según el programa de asistencia de la versión 1 del manifiesto. Los cambios de la versión 1 a la versión 2 pertenecen a dos categorías amplias: cambios en la API y cambios de seguridad.
En este documento, se proporcionan listas de tareas para migrar las extensiones de Chrome de la versión 1 del manifiesto a la versión 2, seguida de resúmenes más detallados de lo que significan estos cambios y por qué se realizaron.
Lista de tareas de los cambios en la API
¿Estás usando la propiedad
browser_actions
o la API dechrome.browserActions
?Reemplaza
browser_actions
por la propiedadbrowser_action
única.Reemplaza
chrome.browserActions
porchrome.browserAction
.Reemplaza la propiedad
icons
pordefault_icon
.Reemplaza la propiedad
name
pordefault_title
.Reemplaza la propiedad
popup
pordefault_popup
(y ahora debe ser una string).¿Estás usando la propiedad
page_actions
o la API dechrome.pageActions
?Reemplaza
page_actions
porpage_action
.Reemplaza
chrome.pageActions
porchrome.pageAction
.Reemplaza la propiedad
icons
pordefault_icon
.Reemplaza la propiedad
name
pordefault_title
.Reemplaza la propiedad
popup
pordefault_popup
(y ahora debe ser una string).¿Estás usando la propiedad
chrome.self
?Se reemplazó por
chrome.extension
.¿Estás usando la propiedad
Port.tab
?Se reemplazó por
Port.sender
.¿Estás usando las APIs de
chrome.extension.getTabContentses()
ochrome.extension.getExtensionTabs()
?Se reemplazó por
chrome.extension.getViews( { "type" : "tab" } )
.¿Tu extensión usa una página de fondo?
Reemplaza la propiedad
background_page
con una propiedadbackground
.Agrega una propiedad
scripts
opage
que contenga el código de la página.Agrega una propiedad
persistent
y configúrala comofalse
para convertir tu página de fondo en una página del evento.
Lista de tareas de cambios de seguridad
¿Estás usando bloques de secuencias de comandos intercalados en páginas HTML?
Quita el código JS dentro de las etiquetas
<script>
y colócalo dentro de un archivo JS externo.¿Utilizas controladores de eventos intercalados (como onclick, etc.)?
Quítalas del código HTML, muévelas a un archivo JS externo y usa
addEventListener()
en su lugar.¿Tu extensión inserta secuencias de comandos de contenido en páginas web que necesitan acceder a los recursos (como imágenes y secuencias de comandos) contenidos en el paquete de la extensión?
Define la propiedad web_accessible_resources y enumera los recursos (y, opcionalmente, una Política de Seguridad del Contenido separada para esos recursos).
¿Tu extensión incorpora páginas web externas?
Define la propiedad sandbox.
¿Tu código o biblioteca usan
eval()
, nuevosFunction()
,innerHTML
,setTimeout()
o, de otro modo, strings de código JS que se evalúan de forma dinámica?Usa
JSON.parse()
si analizas código JSON en un objeto.Usa una biblioteca compatible con CSP, por ejemplo, AngularJS.
Crea una entrada de zona de pruebas en tu manifiesto y ejecuta el código afectado en ella con
postMessage()
para comunicarte con la página de la zona de pruebas.¿Estás cargando código externo, como jQuery o Google Analytics?
Te recomendamos descargar la biblioteca, empaquetarla en tu extensión y, luego, cargarla desde el paquete local.
Agrega a la lista de entidades permitidas el dominio HTTPS que publica el recurso en la sección “content_security_policy” de tu manifiesto.
Resumen de los cambios en la API
La versión 2 del manifiesto presenta algunos cambios en las APIs de acción del navegador y acción de la página, y reemplaza algunas APIs antiguas por otras más nuevas.
Cambios en las acciones del navegador
La API de acciones del navegador presenta algunos cambios de nomenclatura:
- Se reemplazaron las propiedades
browser_actions
ychrome.browserActions
por sus equivalentes singularesbrowser_action
ychrome.browserAction
. En la propiedad
browser_actions
anterior, había propiedadesicons
,name
ypopup
. Estas se reemplazaron por:default_icon
para el ícono de la insignia de acción del navegadordefault_name
para el texto que aparece en la información sobre la herramienta cuando colocas el cursor sobre la insigniadefault_popup
para la página HTML que representa la IU de la acción del navegador (y esta ahora debe ser una string, no puede ser un objeto)
Cambios en las acciones de la página
Al igual que los cambios en las acciones del navegador, la API de acciones de la página también cambió:
- Las propiedades
page_actions
ychrome.pageActions
se reemplazaron por sus equivalentes singularespage_action
ychrome.pageAction
. En la propiedad
page_actions
anterior, había propiedadesicons
,name
ypopup
. Estas se reemplazaron por lo siguiente:default_icon
para el ícono de insignia de acción de la páginadefault_name
para el texto que aparece en la información sobre la herramienta cuando colocas el cursor sobre la insigniadefault_popup
para la página HTML que representa la IU de la acción de la página (que ahora debe ser una cadena, no puede ser un objeto)
APIs que se quitaron y cambiaron
Se quitaron algunas APIs de extensiones y se reemplazaron por equivalentes nuevas:
- La propiedad
background_page
se reemplazó por segundo plano. - Se quitó la propiedad
chrome.self
. Usachrome.extension
. - La propiedad
Port.tab
se reemplazó porPort.sender
. - Las APIs de
chrome.extension.getTabContentses()
ychrome.extension.getExtensionTabs()
se reemplazaron porchrome.extension.getViews( { "type" : "tab" } )
.
Resumen de los cambios de seguridad
Hay varios cambios relacionados con la seguridad que acompañan el cambio de la versión 1 del manifiesto a la versión 2. Muchos de estos cambios se deben a la adopción de Chrome de la Política de Seguridad del Contenido. Te recomendamos leer más sobre esta política para comprender sus implicaciones.
No se permiten las secuencias de comandos intercaladas y los controladores de eventos
Debido al uso de la Política de Seguridad del Contenido, ya no puedes usar etiquetas <script>
intercaladas con el contenido HTML. Estos deben moverse a archivos JS externos. Además, tampoco se admiten los controladores de eventos intercalados. Por ejemplo, supongamos que tienes el siguiente código en tu extensión:
<html>
<head>
<script>
function myFunc() { ... }
</script>
</head>
</html>
Este código provocaría un error en el tiempo de ejecución. Para solucionar este problema, mueve el contenido de la etiqueta <script>
a archivos externos y haz referencia a ellos con un atributo src='path_to_file.js'
.
Del mismo modo, no se ejecutarán los controladores de eventos intercalados, que son una función de caso y conveniencia común que usan muchos desarrolladores web. Por ejemplo, considera instancias comunes, como las siguientes:
<body onload="initialize()">
<button onclick="handleClick()" id="button1">
Estas no funcionarán en las extensiones de Manifest V2. Quita los controladores de eventos intercalados, colócalos en el
archivo JS externo y usa addEventListener()
a fin de registrar controladores de eventos para ellos. Por ejemplo, en tu código JS, usa lo siguiente:
window.addEventListener("load", initialize);
...
document.getElementById("button1").addEventListener("click",handleClick);
Esta es una manera mucho más clara de separar el comportamiento de tu extensión del lenguaje de marcado de su interfaz de usuario.
Incorporación de contenido
En algunas situaciones, la extensión puede incorporar contenido que se puede usar externamente o proveniente de una fuente externa.
Contenido de la extensión en páginas web: Si la extensión incorpora recursos (como imágenes, secuencias de comandos, estilos CSS, etc.) que se usan en secuencias de comandos de contenido que se insertan en páginas web, debes usar la propiedad web_accessible_resources para incluir estos recursos en la lista de entidades permitidas, de modo que las páginas web externas puedan usarlos:
{
...
"web_accessible_resources": [
"images/image1.png",
"script/myscript.js"
],
...
}
Incorporación de contenido externo: La Política de Seguridad del Contenido solo permite que se carguen secuencias de comandos y objetos locales desde tu paquete, lo que impide que atacantes externos introduzcan código desconocido en tu extensión. Sin embargo, hay ocasiones en las que deseas cargar recursos entregados de forma externa, como código de jQuery o Google Analytics. Existen dos maneras de hacerlo:
- Descarga la biblioteca relevante de forma local (como jQuery) y empaquétala con tu extensión.
Puedes flexibilizar la CSP de manera limitada si incluyes orígenes HTTPS en la lista de entidades permitidas de la sección “content_security_policy” de tu manifiesto. Para incluir una biblioteca como Google Analytics, este es el enfoque que se debe seguir:
{ ..., "content_security_policy": "script-src 'self' https://ssl.google-analytics.com; object-src 'self'", ... }
Cómo usar la evaluación dinámica de secuencias de comandos
Quizás uno de los mayores cambios en el nuevo esquema de Manifest v2 es que las extensiones ya no pueden
usar técnicas de evaluación de secuencias de comandos dinámicas, como eval()
o el nuevo Function()
, ni pasar strings de código JS
a funciones que provocarán que se use un eval()
, como setTimeout()
. Además, se sabe que ciertas bibliotecas de JavaScript de uso general, como Google Maps y ciertas bibliotecas de plantillas, utilizan algunas de estas técnicas.
Chrome proporciona una zona de pruebas para que las páginas se ejecuten en su propio origen, a las que se les niega el acceso a Chrome.*
APIs Para usar eval()
y documentos similares de conformidad con la nueva Política de Seguridad del Contenido, debes cumplir las siguientes condiciones:
- Crea una entrada de zona de pruebas en tu archivo de manifiesto.
- En la entrada de la zona de pruebas, enumera las páginas que deseas ejecutar en el espacio aislado.
- Usa los mensajes que se pasan a través de
postMessage()
para comunicarte con la página de zona de pruebas.
Para obtener más detalles sobre cómo hacerlo, consulta la documentación de evaluación de la zona de pruebas.
Lecturas adicionales
Los cambios en la versión 2 del manifiesto están diseñados para guiar a los desarrolladores hacia la compilación de extensiones y apps más seguras y con una arquitectura más sólida. Para ver una lista completa de los cambios de la versión 1 a la 2 del manifiesto, consulta la documentación del archivo de manifiesto. Si quieres obtener más información sobre el uso de la zona de pruebas para aislar el código no seguro, lee el artículo sandboxing eval. Para obtener más información acerca de la Política de seguridad del contenido, visita nuestro instructivo relacionado con las extensiones y una buena introducción a HTML5Rocks.