Sebastian Gomez

Jul 21, 2024

Updated: Jun 24, 2026

Cómo Depurar y Utilizar la API de Runtime en Extensiones de Chrome

Las extensiones de Chrome ofrecen una amplia gama de funcionalidades mediante su API de runtime, que facilita la comunicación entre diferentes componentes de la extensión. En este post profundizaremos en cómo depurar y utilizar esta API para mejorar el funcionamiento de tus extensiones.

Importante (vigente en 2026): Este capítulo usa Manifest V3 (MV3). Chrome empezó a desactivar Manifest V2 en junio de 2024 y el retiro ya está completo en los canales estables, así que las extensiones MV2 ya no se ejecutan ni se aceptan en la Chrome Web Store. Si vienes de un tutorial antiguo con manifest_version: 2, esta es la versión actualizada.

La Importancia de JavaScript en el Desarrollo de Extensiones

Antes de sumergirnos en las técnicas de depuración y el uso de la API de runtime, es crucial destacar la importancia de tener una sólida base en JavaScript. Si aún no te sientes cómodo con JavaScript, te recomiendo pausar el desarrollo de tu extensión y dedicar tiempo a aprender y dominar este lenguaje. Una vez que tengas una buena comprensión de JavaScript, trabajar con extensiones de Chrome será mucho más sencillo.

Configuración Inicial: el archivo Manifest

El archivo manifest.json es el corazón de cualquier extensión de Chrome. Asegúrate de tenerlo correctamente configurado para evitar errores.

Ejemplo de configuración básica en Manifest V3:

{
    "manifest_version": 3,
    "name": "Mi Extensión de Chrome",
    "version": "1.0",
    "permissions": ["storage", "tabs"],
    "host_permissions": ["https://*/*"],
    "background": {
        "service_worker": "background.js"
    },
    "action": {
        "default_popup": "popup.html",
        "default_icon": "icon.png"
    },
    "options_page": "popup.html"
}

Fíjate en los cambios clave respecto a MV2:

• "manifest_version" ahora es 3.
• "browser_action" pasó a llamarse `"action"`.
• El background ya no usa scripts/persistent: en MV3 es un service worker ("service_worker": "background.js"). Si usas módulos ES, añade "type": "module".
• Los patrones de host (https://*/*) van en `host_permissions`, no en permissions.

Tip: Pide solo los hosts que realmente necesites. Patrones amplios como <all_urls> o https://*/* disparan una revisión más estricta en la Chrome Web Store. Para el ejemplo de Pipedrive de más abajo bastaría con "host_permissions": ["https://*.pipedrive.com/*"].

Utilización de la API de Runtime

La API de runtime de Chrome es esencial para manejar eventos y mensajes dentro de tu extensión. Estas APIs se mantienen igual en MV3.

Configuración de un evento de instalación: un caso común es abrir la página de opciones cuando se instala la extensión (recuerda declararla con options_page u options_ui en el manifest, como arriba).

chrome.runtime.onInstalled.addListener(() => {
    chrome.runtime.openOptionsPage();
});

Envío de mensajes entre componentes: puedes enviar mensajes entre popup.js y background.js (el service worker) para manejar interacciones complejas.

Ejemplo en popup.js:

document.getElementById('button').addEventListener('click', () => {
    chrome.runtime.sendMessage({ greeting: 'hello' }, (response) => {
        console.log(response.farewell);
    });
});

Ejemplo en background.js:

chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
    if (request.greeting === 'hello') {
        sendResponse({ farewell: 'goodbye' });
    }
});

Depuración de la Extensión

Depurar extensiones de Chrome puede ser complicado, pero aquí tienes algunos consejos útiles:

Uso de la consola del navegador: abre las herramientas de desarrollo de Chrome (Ctrl+Shift+I, o Cmd+Option+I en Mac) y ve a la pestaña Console para ver errores y mensajes de depuración. Puedes usar console.log en tus scripts para imprimir mensajes y valores importantes.

Depuración del service worker: en MV3, el background.js se ejecuta como service worker y puede "dormirse" cuando está inactivo. Ve a chrome://extensions/, activa el Modo de desarrollador y haz clic en el enlace "service worker" de tu extensión para abrir su consola dedicada. Si no responde, refresca la extensión desde esa misma página para reiniciarlo.

Depuración del `popup.html`: haz clic derecho sobre el popup y selecciona Inspeccionar para abrir las herramientas de desarrollo específicas del popup. Usa la pestaña Network para monitorear las peticiones y asegurarte de que las respuestas sean las esperadas.

Ejemplo Práctico: Integración con Pipedrive

Supongamos que queremos integrar nuestra extensión con Pipedrive para mostrar leads y deals.

Configuración de la página de opciones. En popup.html:

<!DOCTYPE html>
<html>
<head>
    <title>Opciones</title>
</head>
<body>
    <label>Subdominio de API:</label>
    <input type="text" id="subdomain" />
    <label>Token de API:</label>
    <input type="password" id="apikey" />
    <button id="save">Guardar</button>
    <script src="popup.js"></script>
</body>
</html>

En popup.js:

document.getElementById('save').addEventListener('click', () => {
    const subdomain = document.getElementById('subdomain').value;
    const apikey = document.getElementById('apikey').value;
    chrome.storage.local.set({ subdomain, apikey }, () => {
        console.log('Datos guardados');
    });
});

Mostrando leads y deals. En background.js:

chrome.runtime.onInstalled.addListener(async () => {
    const items = await chrome.storage.local.get(['subdomain', 'apikey']);

    // Enviar el token en una cabecera (Authorization), nunca en la URL:
    // así no queda registrado en logs, historiales ni proxies.
    const response = await fetch(
        `https://${items.subdomain}.pipedrive.com/api/v2/deals`,
        {
            headers: {
                'x-api-token': items.apikey,
            },
        },
    );
    const data = await response.json();
    console.log(data);
});

Sobre la autenticación de Pipedrive: El viejo patrón ?api_token=... en la query string es heredado y desaconsejado: una clave en la URL termina filtrándose en logs y en el historial. Hoy Pipedrive recomienda OAuth 2.0 para aplicaciones públicas y su API v2; envía el token en una cabecera y guárdalo de forma segura (como en chrome.storage.local), nunca incrustado en la URL.

Conclusión

Depurar y utilizar la API de runtime de Chrome es crucial para desarrollar extensiones eficientes y funcionales. Asegúrate de tener una base sólida en JavaScript, configura correctamente tu manifest.json en Manifest V3, y aprovecha las herramientas de desarrollo de Chrome, especialmente la consola del service worker, para depurar y mejorar tu extensión. Con estas técnicas podrás crear extensiones potentes y resolver problemas de manera eficaz.

Espero que este post te haya sido útil y te inspire a explorar más las posibilidades que ofrecen las APIs de Chrome. Si tienes preguntas o necesitas asistencia, no dudes en dejar un comentario. ¡Hasta la próxima!