Extensões do Chrome

O JxBrowser fornece a API de extensões que lhe permite instalar, atualizar e desinstalar extensões do Chrome. As extensões funcionam no formato por perfil e não são compartilhadas com outros perfis. Para acessar as extensões de um perfil específico, utilize a seguinte abordagem:

Extensions extensions = profile.extensions();

Se você excluir o perfil, todas as extensões instaladas para este perfil também serão excluídas.

Instalação de extensões

Você pode instalar extensões do Chrome manualmente a partir da Chrome Web Store.

Recomendamos que instale extensões a partir de arquivos CRX se confiar na fonte da extensão. Em comparação com a instalação de extensões a partir da Chrome Web Store, esta lhe oferece as seguintes vantagens:

1. O usuário controla a versão da extensão que instala. Você pode testar a extensão com uma versão específica do JxBrowser e certificar-se de que funciona como esperado com a compilação Chromium que o JxBrowser utiliza. Se você instalar a extensão a partir da Chrome Web Store, você instala a versão mais recente da extensão a qual pode não ser compatível com a versão do JxBrowser que utiliza.
2. Você pode implementar a extensão com a sua aplicação e instalá-la automaticamente. Assim, não é necessário pedir aos usuários que instalem a extensão manualmente a partir da Chrome Web Store.
3. Você pode instalar extensões que não estão disponíveis na Chrome Web Store. Se você desenvolver uma extensão que gostaria de usar no JxBrowser e não quiser publicá-la na Chrome Web Store, você poderá compactá-la num arquivo CRX e usá-la.

Para instalar uma extensão de um arquivo CRX, use a seguinte abordagem:

Extension extension =
        extensions.install(Paths.get("path/to/extension.crx"));

O método retorna uma instância da extensão instalada. Todas as permissões necessárias para a extensão são concedidas automaticamente.

A instalação de extensões da Chrome Web Store está desativada por padrão por motivos de segurança. Se você deseja permitir que os usuários instalem extensões da Chrome Web Store, você precisa autorizar a instalação utilizando a seguinte abordagem:

extensions.set(InstallExtensionCallback.class, (params, tell) -> tell.install());

Sempre que o usuário clicar no botão “Adicionar ao Chrome” na página da Chrome Web Store, será invocada a chamada de retorno InstallExtensionCallback. Você pode obter informações sobre a extensão que o usuário pretende instalar a partir do objeto params e decidir se permite ou não a instalação:

extensions.set(InstallExtensionCallback.class, (params, tell) -> {
    String name = params.extensionName();
    String version = params.extensionVersion();
    if (name.equals("uBlock Origin") && version.equals("1.35.2")) {
        tell.install();
    } else {
        tell.cancel();
    }
});

Para ser notificado quando a extensão for instalada, utilize o evento ExtensionInstalled:

extensions.on(ExtensionInstalled.class, event -> {
    Extension installedExtension = event.extension();
});

Atualizar extensões

Se você instalar uma extensão a partir de um arquivo CRX e pretender atualizá-la com uma nova versão, basta instalá-la a partir de um novo arquivo CRX:

Extension extension =
        extensions.install(Paths.get("path/to/updated_extension.crx"));

Não é necessário eliminar a versão anterior da extensão. O JxBrowser atualizará automaticamente a extensão para a versão mais recente.

Se você instalar uma extensão da Chrome Web Store, você não pode atualizá-la programaticamente. O usuário deve atualizar a extensão manualmente a partir da página da extensão na Chrome Web Store.

Para ser notificado quando a extensão estiver atualizada, utilize o evento ExtensionUpdated:

extensions.on(ExtensionUpdated.class, event -> {
    Extension updatedExtension = event.extension();
});

Desinstalação de extensões

Você pode desinstalar programaticamente a extensão que instalou a partir de um arquivo CRX ou da Chrome Web Store:

extensions.uninstall(extension);

Se a extensão foi instalada manualmente a partir da Chrome Web Store, o usuário poderá querer desinstalá-la também manualmente. Por padrão, a desinstalação de extensões da Chrome Web Store está desativada por motivos de segurança. Se você deseja permitir que os usuários desinstalem extensões da Chrome Web Store ou da página chrome://extensions, você deve autorizar a desinstalação:

extensions.set(UninstallExtensionCallback.class, (params, tell) -> tell.uninstall());

Para ser notificado quando a extensão estiver desinstalada, utilize o evento ExtensionUninstalled:

extensions.on(ExtensionUninstalled.class, event -> {
    String uninstalledExtensionId = event.extensionId();
});

Uma tentativa de trabalhar com uma extensão desinstalada resultará numa ObjectClosedException.

Ação de extensão

As extensões do Chrome podem fornecer funcionalidades que só estão disponíveis no “pop-up de ação da extensão”. Esta é uma caixa de diálogo que é apresentada quando se clica no ícone da extensão na barra de ferramentas do Chrome. Embora o JxBrowser não apresente a barra de ferramentas do Chrome, ele fornece uma API para interagir com o pop-up da ação de extensão.

Para simular o clique no ícone da extensão (ação de extensão) na barra de ferramentas do Chrome para uma aba específica, execute o seguinte código:

// Pense no objeto `browser` como a aba do Chrome atualmente aberta.
extension.action(browser).ifPresent(ExtensionAction::click);

Se você deseja apresentar o ícone da extensão na sua aplicação, pode acessar às propriedades da ação de extensão e subscrever as notificações de atualização da ação:

extension.action(browser).ifPresent(action -> {
    // Obter as propriedades da ação.
    Bitmap icon = action.icon();
    String badge = action.badge();
    String tooltip = action.tooltip();
    boolean enabled = action.isEnabled();

    // Obter notificações quando a ação de extensão estiver atualizada.
    action.on(ExtensionActionUpdated.class, event -> {
        ExtensionAction updatedAction = event.action();
    });
});

Pop-ups de ações de extensão

Quando se cria uma instância de BrowserView, esta registra as implementações padrões da chamada de retorno OpenExtensionActionPopupCallback que apresentará o pop-up da ação de extensão quando o programa simular o clique no ícone da ação de extensão.

Se você deseja apresentar um pop-up de ação de extensão personalizado, registre a sua própria implementação da chamada de retorno OpenExtensionActionPopupCallback:

browser.set(OpenExtensionActionPopupCallback.class, (params, tell) -> {
    Browser extensionActionPopup = params.popupBrowser();
    tell.proceed();
});

Pop-ups de extensão

Algumas extensões podem querer abrir janelas pop-up para exibir um site ou outro conteúdo. Por padrão, o JxBrowser bloqueia esses pop-ups. Para permitir que a extensão mostre pop-ups, registre a sua própria implementação das seguintes chamadas de retorno:

extension.set(OpenExtensionPopupCallback.class, (params, tell) -> {
    Browser extensionPopup = params.popupBrowser();
    tell.proceed();
});

Ou utilizar a implementação padrão:

import com.teamdev.jxbrowser.view.swing.callback.DefaultOpenExtensionPopupCallback;
...
extension.set(OpenExtensionPopupCallback.class,
              new DefaultOpenExtensionPopupCallback());

Peculiaridades e limitações

Criamos a API de extensão com o objetivo de se comportar como o Chromium o tanto quanto possível. Mas como o JxBrowser é um navegador incorporado, não podemos garantir o mesmo comportamento para todos os casos. Assim, existem particularidades e limitações que deve ter em conta ao trabalhar com extensões.

1. Todas abas são abertas como novas janelas.
2. O chrome.tabs.query nunca considera os pop-ups de ações de extensão.
3. As janelas do pop-up da ação de extensão são redimensionáveis automaticamente. O tamanho é regulado pela ação de extensão.
4. Quando o JxBrowser não encontra o manifesto para o envio de mensagens nativas (chrome.runtime.connectNative) no diretório de dados do usuário ou nos dados da aplicação Chromium, ele checa nos dados da aplicação Chrome.

Existem algumas limitações relacionadas com as abas, janelas e outros elementos da IU do Chromium. O windows.Window é mapeado para uma janela nativa associada ao browser, e não para a janela Java em que está incorporado (se existir). Assim, métodos e propriedades do objeto windows.Window, tais como Window.width, Window.height, Window.focused, etc., são vinculados a essa janela nativa.

APIs de extensões não suportadas

Abaixo está a lista de APIs de extensão do Chromium que não são suportadas pelo JxBrowser:

• chrome.tabs.discard
• chrome.tabs.remove
• chrome.tabs.duplicate
• chrome.windows.remove
• chrome.windows.update
• chrome.window.create com mais de um URL nos parâmetros
• chrome.sessions.restore
• chrome.desktopCapture.chooseDesktopMedia.

Se uma extensão chamar um método não suportado que devolva um Promise, será rejeitada com um erro. Se um método aceita um retorno de chamada, a propriedade chrome.runtime.lastError será definida como um erro.

Faça o download do CRX da Chrome Web Store

Se você desejar baixar um arquivo CRX de uma extensão disponível na Chrome Web Store, você pode registrar a chamada de retorno InstallExtensionCallback, onde pode obter um caminho absoluto para o arquivo CRX da extensão que está prestes a ser instalada a partir da Chrome Web Store e fazer uma cópia do mesmo para uma localização diferente:

extensions.set(InstallExtensionCallback.class, (params, tell) -> {
    String name = params.extensionName();
    String version = params.extensionVersion();
    File sourceCrxFilePath = Paths.get(params.extensionCrxFile()).toFile();
    File targetCrxFilePath = Paths.get(name + "-" + version + ".crx").toFile();
    try {
        Files.copy(sourceCrxFilePath, targetCrxFilePath);
    } catch (IOException e) {
        throw new RuntimeException(e);
    }
    tell.cancel();
});

Agora, você pode carregar a extensão necessária na Chrome Web Store e clicar no botão “Adicionar ao Chrome”. A chamada de retorno será invocada e o arquivo CRX da extensão será copiado para a localização especificada.