Documentation

Installing the AEM Sidekick

Last update: Fri May 17 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

​​The AEM sidekick provides content authors with a toolbar offering context-aware options so that they can edit, preview, and publish their content directly from the pages of your website.

This document explains how to install and configure the sidekick.

Installation Options

The sidekick is available as a browser extension in Chrome-based browsers and Safari and can be installed in a number of ways.

If you already have the sidekick installed and need help using it, please see the document Using the AEM Sidekick Extension.

Using the Sidekick Configurator

The configurator detects your browser and guides you through the installation process.

  1. In Safari or a Chrome-based browser, navigate to the link https://www.aem.live/tools/sidekick/
  2. Provide the URL to the GitHub repository of your project and optionally a name for the project and click Go.
    1. The sidekick supports multiple projects and providing a descriptive name helps managing the configurations.
  3. In the new section Install the Sidekick extension and add this project that appears, click the Install Sidekick Extension for Chrome or Install Sidekick Extension for Safari.
    Sidekick configurator without Sidekick extension installed
  4. The page will then open the App Store or Chrome Web Store as appropriate where you can install the extension as appropriate to your OS.
  1. Return to the page of the configurator and click Add project.
    Sidekick configurator with Sidekick extension installed and project not configured yet
  2. The configurator adds the project to the extension. You are now ready to use the extension!

If you have any issues installing the extension, please review the instructions in the section Manually Installing the Sidekick.

Manually Installing the Sidekick

Chrome

  1. Navigate to the sidekick extension in the Chrome Web Store.
  2. Click the Add to Chrome button.
  3. Click Add extension to confirm the installation.
  4. Click the new Adobe Experience Cloud icon next to Chrome’s address bar and click the Pin icon to keep it visible.

Safari

  1. Navigate to the sidekick extension in the App Store.

  2. Click the Install button.

  3. Enable the extension.

    1. Desktop Safari

      1. Open Safari.
      2. Go to Settings.
      3. Click Extensions.
      4. Check the box next to the sidekick extension.

    2. Mobile Safari

      1. Open Settings
      2. Tap Safari
      3. Then tap Extensions.
      4. Toggle the sidekick extension.

  4. Make sure the extension is allowed access to all websites.

  5. If your project requires you to sign in to use the sidekick extension, you need to enable 3rd-party cookies: Safari > Settings > Privacy > uncheck “Prevent cross-site tracking”

Adding Your Project

There are multiple ways to add projects to the sidekick extension:

1. Sidekick Configurator

  1. See the section Using the Sidekick Configurator.

2. Sharing URL

  1. Navigate to a sharing URL starting with https://www.aem.live/tools/sidekick/?...
  2. Click the blue Add Project button.
    1. Alternatively, you can click the Adobe Experience Cloud icon next to your browser’s address bar and select Add Project from the context menu.
  3. A dialog will be shown for confirmation. Click OK to continue.

A colleague on the project can provide you with a sharing URL. See the document Using the AEM Sidekick Extension for details.

3. Project URL (Desktop Only)

  1. Navigate to a project URL with a host name like this: https://main–repo–owner.hlx.page/
  2. Click the Adobe Experience Cloud icon next to your browser’s address bar and select Add Project from the context menu.
  3. A dialog will be shown for confirmation. Click OK to continue.

4. GitHub Repository URL (Desktop Only)

  1. Navigate to a GitHub repository starting with https://github.com/...
  2. Click the Adobe Experience Cloud icon next to your browser’s address bar and select Add Project from the context menu.
  3. A dialog will be shown for confirmation. Click OK to continue.

5. Options Page

The options page lists all project configurations and allows you to add, edit or delete them.

  1. Go to the options page:

    1. Chrome: Right-click the Adobe Experience Cloud icon next to the address bar and select Options from the context menu.
    2. Safari (desktop): Right-click the Adobe Experience Cloud icon next to the address bar and select Manage Extension… In the extensions dialog, click Preferences.
    3. Safari (mobile): Open Settings and tap Safari > Extensions > AEM Sidekick > Extension settings.

  2. Add a project configuration using one of the two following methods:

    1. Add via sharing URL: the project configuration will be retrieved from the parameters contained in the share URL.
    2. Add manually: enter the GitHub repository URL and other optional parameters for your project.

Understanding Project Configurations

Project configuration editor

  • Project Name : Specify your project name here. This would give a name to the project configuration, making it easy to identify in the sidekick. This is an optional configuration.
  • Repository URL : Specify the Github repository of your project here. For e.g. https://github.com/hlxsites/wknd.
  • Content URL : Specify the url of the project’s root folder in Sharepoint / GDrive root.
  • Production Hostname : Specify the production URL (the domain name being your project’s public host name). This would ensure that the sidekick is available in the browser when you open the site on the production domain. This is an optional setting.

Advanced Configuration

Develop Sidekick Customizations locally

Advanced project configuration settings

  • Test project configuration locally : Use this advanced setting for testing any local customizations in the sidekick. Read more about Sidekick Customizations here.
    • Local Development URL : Specify the url of your locally running server. Default value is http://localhost:3000

Add custom Authorization

For sites that are protected with authentication on .page and .live, you can add an Authorization token that will be added to the HTTP Authorization: header.

This can be used to test the API keys used in your CDN, and make sure that they have access to the origin. This option is likely to only be used by administrative staff for setup and debugging purposes.

Installing the Sidekick Bookmarklet

If you are unable to install an extension in your browser, or if you use a browser that is not currently supported by the sidekick extension, you can use a bookmarklet.

A bookmarklet is a browser bookmark or favorite containing JavaScript commands that add new features to the browser. The sidekick bookmarklet adds the features of the sidekick without requiring any installation, which can be useful to some users.

Because the sidekick extension remembers whether it is open or closed on a given content page, Adobe recommends installing the extension if possible. The bookmarket must always be manually opened and closed on your content pages.

To install the bookmarklet:

  1. In your browser, navigate to the link https://www.aem.live/tools/sidekick/
  2. Provide the URL to the GitHub repository of your project and optionally a name for the project and click Go.
    1. The sidekick supports multiple projects and providing a descriptive name helps managing the configurations.
  3. A new section called Install Sidekick Bookmarklet for this project appears on the page along with a button.
    Sidekick configurator with Sidekick extension installed and project configured
  4. Drag the button to your bookmarks or favorite toolbar.
  5. Click the bookmarklet in the bookmarks or favorites toolbar to toggle it.

Use the Sidekick Extension

Please see the document Using the AEM Sidekick to learn how to use the sidekick.

recommendation-more-help
10a6ce9d-c5c5-48d9-8ce1-9797d2f0f3ec