DocumentationAEMAEM TutorialsAEM as a Cloud Service Tutorials

Verify an extension

Last update: Fri Jan 26 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Beginner
  • Developer

AEM UI extensions can be verified against any AEM as a Cloud Service environment in the Adobe Org the extension belongs to.

Testing an extension is done through a specially crafted URL that instructs AEM to load the extension, only for that request.

https://video.tv.adobe.com/v/3412877?quality=12&learn=on

Transcript
So there are two primary ways to test and validate an AEM content fragment console extension. The first way is typically used by developers as they are developing an application to test it out and to verify that it’s working, debug it, et cetera within the context of the content fragment console. So for this, within the application, you simply run the application. So aio app run, and this is going to run the application on my local development machine.
So with our app started up, we can see that it is being run locally on https local host port 9080.
And what we need to do now to see it in action is mount it on an AEM as a cloud service content fragment console. And so for this, we actually need a true AEM as a cloud service environment. So I have opened up a dev environment over here on Author and I’ll open up the content fragment console.
And what we’re going to do is essentially mount our local application onto this content fragment console. So to do this, we just have to manipulate the URL and we’re going to add a couple query parameters. So I definitely recommend adding these query parameters at the beginning and not after the repo. And this is because if you look closely the repo URL uses a hash. So any query parameters that you might add after this hash will not actually be treated as query parameters. They’ll be treated as part of the hash. So to avoid any confusion, try to always put these at the beginning. So the first query parameter we’ll add is dev, capital M mode equals true.
And then another query parameter, and ext for extension equals, and this is going to be whatever the URL to the local application is as shown here in your CLI after running aio app run. So we’ll go ahead and paste that in here. So it’s just https://localhost:9080. And of course, we have to make sure that we put another ampersand to delimit the repo query parameter.
So now, if I hit enter, it’s going to reload and it should be loading the content fragment extension running locally on port 9080 in my content fragment console only for this browser window. So this would not affect anybody else using this content fragment console since this is a local mount.
So my application has a action bar. So let me go ahead and select a couple of these. And ideally, what we see is our action bar button showing up here in the action bar.
It’s not, and this is because on the first access, you might have to do this once a day, is you need to accept the SSL certificate for https local host 9080.
So our local is running on https. We don’t actually have a valid cert for that locally. So what we need to do is simply access local host 9080 on https in our browser and go through the browser and accept the certificate.
And you should see something that says, "Iframe for integration with Host " display. It will say non-secure, this is fine since this is only for local development. Once we have this, we can close and we can refresh this page.
Now, when we select some again, you can see that we do, in fact, have the custom extension action bar button injected into the page. And so from here, we can test this out and do whatever we want to and begin developing and validating against a real content fragment console.
Do note that any changes to the extension that are made locally are hot reloaded in this context as well. So that’s pretty nice.
All right, so the second way to test out an extension is typically used when you need to have a business users or UAT testers valid in extension. So these are users that typically are not developers and cannot run the app locally and test it using this local mount method. So let’s take a look at how we do this. Let’s hit control C to terminate our local development environment. And what we want to do here is deploy our build to one of the non-production workspaces for our Adobe developer console project. So we can switch between workspaces by using aio app use, dash W, and then specify the workspace. So typically, Stage is used but if you did have other custom workspaces created, you could always deploy to those. Let’s go ahead and merge all of the environment in aio changes required to deploy to the Stage environment. And you can see here that now we are targeting Stage.
And now, we simply just have to run aio app deploy and this will build and deploy our app to our Stage environment.
All right, looks like it’s done. So in order to review and validate the bill deployed to the Stage workspace, we do something very similar to what we did for the local dev, but instead of using the https local host 9080, we’re going to use this deployed application URL specified here. So we’ll simply copy this and, just like before, we need the devMode query parameter set to true. And then ext query parameter, instead of being set to local host 9080, will be set to this full URL, Just go ahead and paste that in. Hit enter.
When it reloads, let’s again select a couple of these in. We can see that our action bar is in fact displaying here. And this action bar this time is being loaded from the Stage workspace and not our local development runtime.
Now, you can take this URL that you’ve created and you can send it off to anyone that needs to validate and test this build of the extension. -
IMPORTANT
The video above showcases the use of a Content Fragment Console extension to illustrate App Builder extension app preview and verification. However, it’s important to note that the concepts covered can be applied to all AEM UI extensions.

AEM UI URL

AEM Content Fragment Console URL {align="center"}

To create a URL that mounts the non-production extension into AEM, the URL of the AEM UI the extension is injected into must be obtained. Navigate to the AEM as a Cloud Service environment to verify the extension on, and open the UI the extension is to be previewed on.

For example, to preview an extension for the Content Fragment console:

  1. Log in to the desired AEM as a Cloud Service env.

  2. Select the Content Fragments icon.

  3. Wait for the AEM Content Fragment Console to load in the browser.

  4. Copy the AEM Content Fragment Console’s URL from the browser’s address bar, it should resemble:

    code language-none 
    https://experience.adobe.com/?repo=author-p1234-e5678.adobeaemcloud.com#/@wknd/aem/cf/admin

This URL is used below when crafting the URLs for development and stage verification. If verifying the extension against other AEM UIs, obtain those URLs and apply the same steps below.

Verify local development builds

  1. Open a command line to the root of the extension project.

  2. Run the AEM UI extension as a local App Builder app

    code language-shell 
    $ aio app run
...
No change to package.json was detected. No package manager install will be executed.

To view your local application:
  -> https://localhost:9080
To view your deployed application in the Experience Cloud shell:
  -> https://experience.adobe.com/?devMode=true#/custom-apps/?localDevUrl=https://localhost:9080

Take note of the local application URL, shown above as -> https://localhost:9080

  1. Initially (and whenever you see a Connection Error) open https://localhost:9080 (or whatever your local application URL is) in your web browser, and manually accept the HTTPS certificate.

  2. Add the following two query params to the AEM UI’s URL

    • &devMode=true
    • &ext=<LOCAL APPLICATION URL>, usually &ext=https://localhost:9080.

    Add the two above query parameters (devMode and ext) as the first query parameters in the URL. AEM’s extensible UI’s use hash routes (#/@wknd/aem/...), so incorrectly post-fixing the parameters after the # does not work.

    The preview URL should look like:

    code language-none 
    https://experience.adobe.com/?devMode=true&ext=https://localhost:9080&repo=author-p1234-e5678.adobeaemcloud.com#/@wknd/aem/cf/admin

  3. Copy and paste the preview URL into your browser.

    • You may have to initially, and then periodically, accept the HTTPS certificate for the local application’s host (https://localhost:9080).

  4. The AEM UI loads with the local version of the extension injected into it for verification.

IMPORTANT
Remember, when using this approach, the extension under development only impacts your experience, and all other users of the AEM UI experience the UI without the injected extension.

Verify stage builds

  1. Open a command line to the root of the extension project.

  2. Ensure that the Stage workspace is active (or whichever Workspace is used for verification).

    code language-shell 
    $ aio app use -w Stage

    Merge any changes to .env and .aio.

  3. Deploy the updated extension App Builder app. If not logged in, run aio login first.

    code language-shell 
    $ aio app deploy
...
Your deployed actions:
web actions:
  -> https://98765-123aquarat.adobeio-static.net/api/v1/web/aem-cf-console-admin-1/generic
To view your deployed application:
  -> https://98765-123aquarat.adobeio-static.net/index.html
To view your deployed application in the Experience Cloud shell:
  -> https://experience.adobe.com/?devMode=true#/custom-apps/?localDevUrl=https://98765-123aquarat.adobeio-static.net/index.html
New Extension Point(s) in Workspace 'Production': 'aem/cf-console-admin/1'
Successful deployment 🏄

  4. Add the following two query params to the AEM UI’s URL

    • &devMode=true
    • &ext=<DEPLOYED APPLICATION URL>

    Add the two above query parameters (devMode and ext) as the first query parameters in the URL, as extensible AEM UIs use a hash route (#/@wknd/aem/...), so incorrectly post-fixing the parameters after the # does not work.

    The preview URL should look like:

    code language-none 
    https://experience.adobe.com/?devMode=true&ext=https://98765-123aquarat.adobeio-static.net/index.html&repo=author-p1234-e5678.adobeaemcloud.com#/@wknd/aem/cf/admin

  5. Copy and paste the preview URL into your browser.

  6. The AEM Content Fragment Console injects the version of the extension deployed to Stage workspace in. This Stage URL can be shared to QA or business users for verification.

Remember, when using this approach, the Staged extension is only injected on AEM Content Fragment Console’s when access with the craft Stage URL.

  1. Deployed extensions can be updated by running aio app deploy again, and these changes automatically reflect when using the preview URL.
  2. To remove an extension for verification, run aio app undeploy.

Preview bookmarklet

To ease the creation of preview and preview URLs described above, a JavaScript bookmarklet that loads the extension can be created.

The bookmarklet below previews the local development builds of the extension on https://localhost:9080. To preview stage builds, create a bookmarklet with the previewApp variable set to the URL of the deployed App Builder app.

  1. Create a bookmark in your browser.

  2. Edit the bookmark.

  3. Give a bookmark a meaningful name, such as AEM UI Extension Preview (localhost:9080).

  4. Set the bookmark’s URL to the following code:

    code language-javascript 
    javascript: (() => {
    /* Change this to the URL of the local App Builder app if not using https://localhost:9080 */
    const previewApp = 'https://localhost:9080';

    const repo = new URL(window.location.href).searchParams.get('repo');

    if (window.location.href.match(/https:\/\/experience\.adobe\.com\/.*\/aem\/cf\/(editor|admin)\/.*/i)) {
        window.location = `https://experience.adobe.com/?devMode=true&ext=${previewApp}&repo=${repo}${window.location.hash}`;
    }
})();

  5. Navigate to an extensible AEM UI to load the preview extension on, and then click the bookmarklet.

TIP
If the App Builder extension does not load, when using, &ext=https://localhost:9080, open that host and port directly in a browser tab, and accept the self-signed certificate. Then try the bookmarklet again.
recommendation-more-help
4859a77c-7971-4ac9-8f5c-4260823c6f69