Service worker API reference

service Worker de Servicio de Referencia

Un service Worker hereda todas las limitaciones y los comportamientos disponibles para service Workeres Compartidos de HTML5. Puede crear XMLHttpRequests, usar WebSockets, recibir mensajes de ventanas y del navegador, usar IndexedDB, y publicar mensajes a otras ventanas.

El service Worker puede usar los métodos ononline, onoffline, y navigator.online y las propiedades que están disponibles para todos los service Workeres para obtener una notificación del estado online/offline de los navegadores.

Además de los métodos estándar, los Service Wokers tienen acceso a funciones adicionales, todas las cuales están implementadas usando mensajes enviados y recibidos por un service Worker "puertos de mensaje". Así como los puertos de mensaje son inherentemente asíncronos, cualquier mensaje que necesite una respuesta involucrará dos mensajes - uno para la pregunta y otro para la respuesta. No todos los mensajes requieren respuesta - esto es parte de la especificación del mensaje. Los mensajes que no requieran una respuesta son análogos a un 'evento' no solicitado. Si un mensaje sí requiere una respuesta, entonces la respuesta siempre deberá ser enviada en el mismo puerto de la petición y en general, el 'asunto' de la respuesta será el asunto de la petición con "-respuesta" concatenado.

Se espera que los service Workeres de Servicio provean una función en un ámbito global, nombrado onconnect. El navegador invocará onconnect durante la fase de arranque,pasando un evento. El service Worker debería acceder a la propiedad ports de este evento para extraer una comunicación estable hacia el puerto del navegador, y persiste por el ciclo de vida del service Worker, como esto:

var apiPort;
var ports = [];
onconnect = function(e) {
    var port = e.ports[0];
    ports.push(port);
    port.onmessage = function (msgEvent)
    {
        var msg = msgEvent.data;
        if (msg.topic == "social.port-closing") {
            if (port == apiPort) {
                apiPort.close();
                apiPort = null;
            }
            return;
        }
        if (msg.topic == "social.initialize") {
            apiPort = port;
            initializeAmbientNotifications();
        }
    }
}

// send a message to all provider content
function broadcast(topic, data) {
  for (var i = 0; i < ports.length; i++) {
    ports[i].postMessage({topic: topic, data: data});
  }
}

Cada mensaje tiene un elemento con 2 campos: 'topic' y 'data'. El topic identifica el método o evento que es utilizado, y el data especifica datos adicionales únicos al topic. Todos los métodos estandarizados y eventos tienen topics que comienzan con "social." - esto significa que los servicios son libres de usar topics sin este prefijo como un detalle de implementación privada (por ejemplo, para comunicar algún contenido de un servicio a un service Worker de servicio).

Serialización de mensajes

Para un mensaje con el asunto topic y los argumentos (arg1:val1, arg2:val2), construye un objeto como:

{ topic: topic, data: { arg1: val1, arg2: val2 } }

Mensajes de Control enviados a service Workeres de servicios

social.initialize

Enviados por el navegador durante el arranque. Cuando el JavaScript de un service Worker ha sido cargado con éxito y evaluado, el navegador enviará un mensaje con este asunto. Cuando el service Worker recibe el social.initalize event, debería enviar ambos, el social.user-profile y, si los Mrcadores de Página son soportados [como en Fx23], el mensaje desocial.page-mark-config.

social.port-closing

Enviado por el navegador durante el apagado del service Worker, cuando un PuertodeMensaje para el service Worker está a punto de ser cerrado. Este será el último mensaje que el service Worker recibirá en el puerto.

Mensajes de Control enviados desde el service Worker de Servicio al navegador

social.reload-worker

Enviado por el service Worker para solicitar al navegador que re-cargue al service Worker.

social.cookies-get

Enviado por el service Worker para solicitar al navagador que responda con una lista del mismo origen de las cookies para el proveedor. El navegador responderá con un mensaje social.cookies-get-response.

social.request-chat

Enviado por el service Worker para solicitar al navagador que abra un nuevo panel de chat flotante con la URL especificada. La ventana de chat abierta por el service Worker será abierta en un modo minimizado.

Argumentos:

URL

Cadena, requerida. La URL de la página de chat para abrir en la ventana.

Control de Notificación de Ambiente

social.user-profile

Enviada por el service Worker, para establecer las propiedades para el proveedor de icónico de perfil de usuario de datos usado para el botón de la barra. Si el retrato de usuario y userName no se encuentran, el botón de IU indicará el estado de no-logueado. Cuando esté indicando un estado de no-logueado, los íconos de estado establecidos vía social.ambient-notification serán removidos. Un servicio que no maneja el loguéo de usuarios deberá enviar este mensaje con los alores apropiados para el sitio, como lo son el ícono del sitio, URL principal y el nombre de la marca.

Argumentos:

iconURL

Cadena, requerida. Si es sumistrada, especifíca la URL hacia una imagen 16x16 pixeles usada por el ícono de estado. El iconURL puede ser una URL de datos con una imagen codificada para evitar solicitudes a los http (ejemplo: "data:image/png;base64,...data...").

portrait

Cadena, opcional. Si es suministrada, especifíca la URL hacia una imagen de 48x48 pixeles del usuario. El retrato puede ser una URL de datos con una imagen codificada para evitar solicitudes a los http.

userName

Cadena, opcional. El nombre de la cuenta mostrado con el retrato en el menú de proveedor.

dispayName

Cadena, requerido. Nombre real del usuario usado para propósitos de visualización en varios elementos de IU.

profileURL

Cadena, requerido. URL a  la página de perfil de un usuario logueado. Este será abierto en una pestaña normal del navegador cuando el nombre de usuario es cliqueado.

social.ambient-notification

Enviado por el service Worker, para actualizar o crear un ambiente de íconos de notificaciones. Es enviado uno por cada ícono. Un usuario debe estar logueado para mostrar los íconos de estado, y deberás llamar a social.user-profile antes de llamar social.ambient-notification para establecer los íconos de estado.

Argumentos:

name

Cadena. Un identificador para el ícono. La primera vez que un nombre dado es mostrado, eficazmente crea un nuevo ícono. Si el mismo nombre es usado en llamadas sub-secuentes, el ícono existente es actualizado.

iconURL

Cadena, opcional. Si es suministrada, especifíca la URL hacia una imagen de 16x16 pixeles usada para el ícono de estado. El iconURL puede ser una URL con una imagen codificada para evitar solicitudes a los http (ejemplo: "data:image/png;base64,...data...")

counter

Número, opcional. Especifíca un númeroque será sobre-puesto sobre el ícono, típicamente usado para transmitir un concepto unread.

contentPanel

Cadena, opcional. Especifíca la URL de un contenido que será mostrado en el panel popup para el ícono.

Control de Notificaciones Activo

social.notification-create

Enviado por el service Worker, para crear y mostrar un objeto de notificación. Esto solicita que el navegador notifique al usuario de un relevante e inmediato cambio de estado. Ver https://developer.mozilla.org/en/DOM/navigator.mozNotification para más detalles. Cuando el usuario cliquea en la notificación, el mensaje social.notification-action es enviado al service Worker. El título de la notificación siempre será el nombre del proveedor.

NOTA: Queremos aumentar el objeto mozNotification definido en los documentos con un "tipo" de campo adicional. Detalles TBD. NOTA: No hay manera de almacenar la duración y tampoco de "cancelar" una notificación (la hipótesis es de que son de muy corta duración). ¿Está bien?

Argumentos:

id

Cadena: Un ID para la notificación. Este ID no será mostrado pero será pasado atrás vía el evento social.notification-action si el usuario cliquea en la notificación.

type

Cadena: La cadena Tipo deberá ser consistente para cada tipo de notificación. Este será usado por algun sistema de notificación para proveer filtraciones de notificaciones al nivel del usuario. Un proveedor deberá elegir cualquier cadena para el tipo, pero deberá mantener los tipos de cadena consistentes y descriptivos para cada tipo de acción. Por ejemplo, las notificaciones de chat deberían siempre de tener la cadena del mismo tipo. Sugerencia/ejemplo que incluye la notificación:

• social.providername.chat-request
• social.providername.friend-request
• social.providername.activity (e.g. someone posted to your activity stream)

icon

Cadena/nulo. La URL de una imagen a ser colocada en una notificación. Mientras que esta puede ser cualquier RL válida, los implementadores están muy recomendados que usen una URL de datos para minimizar la latencia.

body

Cadena: El cuerpo del mensaje de notificación. este cuerpo será tomado como un super-enlace y podrá ser cliqueado. El marcado de HTML no es soportado.

action

Cadena: Una acción para ejecutar cuando el usuario hace clic en la notificación. Si ninguna acción es prevista, la notificación no es cliqueable. Acualmente las únicas acciones soportadas son link, callback y openServiceWindow. Si la acción está difinida, actionArgs también deberá ser definida.

actionArgs

Objeto: Una objeto con argumentos (abajo). Acciones soportadas y sus actionArgs son:

• link
  • toURL: Cadena: URL para abrirse en una nueva pestaña de navegador.

social.notification-action

Enviada al service Worker como una respuesta a la notificación "callback", después de que el usuario ha cliqueado en la notificación.

Argumentos:

id

Cadena: el ID de la notificación que fue cliqueada.

action

Cadena: La acción enviada en social.notification-create.

actionArgs

Objeto: Las actionArgs enviados en social.notification-create.

Marcadores de página

ESTADO: CON MIRA EN Fx23 (reemplazando Link Recommendation below)

Las Marcas de Página son un simple mecanismo de compartir una URL con un proveedor social. Las Marcas de Página difieren para compartir en que la URL solo es enviada al proveedor. Esta funcionalidad puede manejar casos de uso como el Me Gusta de Facebook, Google +1, Pocket, u otras características como ver-más-tarde. Cuando estan habilitados, y el botón adicional de Marca aparecerá al final de la botonera Social en Firefox. No hay una IU asociada con otro botón que no sea el cambiar la imagen de botón para reflejar el estado de marcado o no-marcado.

social.page-mark-config

Enviado por el service Worker para notificar a Firefox de soporte para las Marcas de Página. Este mensaje puede ser enviado en cualquier momento. Te recomendamos mandarlo cuando se esté manejando el mensaje social.initialize.

Argumentos:

images

Objeto. Debe tener dos llaves de tipo String, 'marked' y 'unmarked', los cuales serán usados como ícono del botón de Marcador de Página. El agente de usuario buscará si la actual página ha sido marcada - si sí, mostrará la imagen 'marked', de otra manera motrará la imagen 'unmarked'. Puede contener una imagen direccionable - web o una URL de datos conteniendo una imagen de datos generada dinamicamente.  Implementadores están fuertemente recomendados de usar una URL de datos para minimizar la latencia. Cada imagen se espera que sea de de 16x16 píxeles.

messages

Objeto. Debe tener las siguientes llaves de cadena:

• 'markedTooltip', 'unmarkedTooltip': Las cadenas usadas como la barra de herramientasen el objetivo de clic cuando las imagenes 'marked' y 'unmarked', respectivamente, son mostradas.
• 'markedLabel', 'unmarkedLabel': Cadenas que serán utilizadas para actualizar una etiqueta después de la acción 'marked' o 'unmarked' es hecha, para reflejar la transición desde marked-to-unmarked o vice-versa.

social.page-mark

Enviado por el navegador hacia el service Worker cuando el usuario 'marca' o 'desmarca' una página. No hay respuesta esperada. El navegador rastreará el estado de la marca de la página separadamente del proveedor. Si el usuario limpia su historial, todas las marcas de página serán removidas.

Arguments:

url

Cadena. La URL de la página es marcada.

marked

Boolean.

Enlace de Control de Recomendación

NOTA: El siguiente mensaje usuario-recomendación fue RECHAZADO y REMOVIDO de Fx23. Fue reemplazado por Page Marks.

social.user-recommend-prompt

ESTADO: RECHAZADO, REMOVIDO de Fx23, REEMPLAZADO CON social.page-mark-config

Enviado por el navegador para solicitar una vista de la interfaz para la "recomendación de usuario". El service Worker debe responder con una user-recommend-prompt-response

Nota que tipicamente este mensaje solo será enviado cuando un proveedor está activado y la respuesta será usada para todas las URL's. En otras palabras, el proveedor no espera que este mensaje sea enviado cada vez que el agente de usuario navega o muestra una nueva UTL.

Arguments:

None

social.user-recommend-prompt-response

STATUS: DEPRECATED, REMOVED Fx23

The Worker constructs and posts a user-recommend-prompt-response in response to a social.user-recommend-prompt message received from the browser. See social.user-recommend-prompt for more details.

Arguments:

images

Object. Must have 2 string keys, 'share' and 'unshare', which each value being the URL to an image which will be set as the "src" property of an image contained in the user-facing click target for the "recommend" action. The user agent will track if the current page has been shared - if so, it will show the 'unshare' image, otherwise will show the 'share' image. It can contain a web-addressible image or a data URL containing dynamically-generated image data. Implementors are strongly encouraged to use a data URL to minimize latency. Each image is expected to be 16px wide and 16px high.

messages

Objeto. Debe tener las siguientes llaves de cadena:

• 'shareTooltip', 'unshareTooltip': Las cadenas usadas como el tooltip en el objetivo de clic cuando las imagenes de 'share' y 'unshare', respectivamente, son mostradas.
• 'sharedLabel', 'unsharedLabel': Cadenas que serán usadas para actualziar una etiqueta de widget después de que la acción de 'share' o 'unshare' es tomada para reflejar la transición desde shared-to-unshared o vice-versa. Notese que en Fx17, las etiquetas no son visibles pero son usadas como una ayuda de accesibilidad así que un screen-reader o similar puede hacer notar la transición.
• 'unshareLabel': Una cadena a sermostrda en el 'unshare popup' para reflejar que el item ha sido compartido. Ejemplo: "Ya has compartido esto".
• 'portraitLabel': Una cadena usada como la aria-label para la imagen de perfil de usuario sea mostrada como 'unshare popup'. Ejemplo: "Tu imagen de perfil".
• 'unshareConfirmLabel': Una cadena usada como la etiqueta en el botón en la 'unshare popup' usada para modificar el 'unshare'. Ejemplo: "No compartir esto".
• 'unshareConfirmAccessKey': Una cadena usada como la llave de acceso para el boton de No comprtir. Tipicamente esta debería ser una etiqueta en la cadena 'unshareConfirmLabel'.
• 'unshareCancelLabel': Una cadena usada como la etiqueta en el botón en la 'unshare popup' cuando el usuario decide seguir continuando el elemento. Ejemplo: "Cerrar".
• 'unshareCancelAccessKey': Una cadena usada como la llave de acceso para el botón de No compartir.

social.user-recommend

ESTADO: RECHAZADA, REMOVIDO DE Fx23, REEMPLAZADO CON social.page-mark

Indica que el usuario ha hecho clic en el elemento de interfaz "user recommendation". El mensaje incluye:

Argumentos:

url

Cadena, requerida. La URL que el usuario está viendo, incluída la cadena de busqueda, pero menos cualquier texto de hash, de la raíz de la actual vista del navegador.

No es necesaria una respuesta; como fuere, el servicio debe responder en el mismo puerto con una usuario-recomendación-prompt-respuesta si el objetivo de clic debe cambiar su apariencia.

social.user-unrecommend

ESTADO: RECHAZADO, REMOVIDO DE Fx23

Indíca que al usuario le gustaría volver a su previa recomendación. El mensaje incluye:

Argumentos:

url

Cadena, requerido. La URL que el usuario está viendo, incluyendo la cadena de consulta, pero no los textos de hash, de la raíz del contexto actual de vista del navegador.