Skip to content

DA App SDK

Jump to bottom
Chris Millar edited this page Oct 17, 2024 · 11 revisions

The Dark Alley App SDK allows you to work with protected Dark Alley content. This allows you to build fully authenticated custom apps for your creators when you have a special use case Dark Alley does not cover out of the box.

Supported experiences

  1. Fullscreen apps - Great for creating first-class fullscreen apps that can integrate with the entire Adobe Experience Cloud
  2. Library plugins - Great for enabling integrations into DA's library.

Example

You will need

  1. A site - ex: https://main--geometrixx--aemsites.aem.live
  2. A page - ex: https://main--geometrixx--aemsites.aem.live/tools/tags.html
  3. An app - ex: https://main--geometrixx--aemsites.aem.live/tools/tags/tags.js

Build

Note

The SDK is based on the secure PostMessage API. This API allows the SDK to securely pass messages between DA and your application. While not required, importing the SDK in HTML is recommended as it will ensure your application is ready to receive messages from DA.

/tools/tags.html

<!DOCTYPE html>
<html>
  <head>
    <title>DA App SDK Sample</title>
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <link rel="icon" href="data:,">
    <!-- Import DA App SDK -->
    <script src="https://da.live/nx/utils/sdk.js" type="module"></script>
    <!-- Project App Logic -->
    <script src="/tools/tags/tags.js" type="module"></script>
  </head>
  <body>
  </body>
</html>

/tools/tags/tags.js

// Import SDK
import DA_SDK from 'https://da.live/nx/utils/sdk.js';

// Import Web Component
import './tag-browser.js';

(async function init() {
  const { context, token, actions } = await DA_SDK;
  const tagBrowser = document.createElement('da-tag-browser');
  tagBrowser.project = context.repo;
  tagBrowser.token = token;
  tagBrowser.actions = actions;
  document.body.append(tagBrowser);
}());

/tools/tags/tagbrowser.js

import { LitElement } from 'https://da.live/deps/lit/lit-all.min.js';

export default class DaTagSelector extends LitElement {
  static properties = {
    project: { type: String },
    token: { type: String },
    actions: { type: Object },
    parent: { type: Object },
  };

  myButtonClicked(e) {
    e.preventDefault();

    // ... collect the text to insert in the document
    const newText = ...

    this.actions.sendText(newText); // Put the text at the cursor in the doc
    this.actions.closeLibrary();    // Optional, this will close the plugin widget
  }

Optional: /tools/sidekick/config.json

If you wish to create a library plugin, you will need to add a plugin entry in your sidekick config.json.

"plugins": [
    {
      "id": "tags",
      "title": "Tag Browser",
      "environments": ["da-edit"],
      "path": "/tools/tags.html"
    }
]

Test

Visit (fullscreen): https://da.live/app/aemsites/geometrixx/tools/tags?ref={branch-name}

Visit (library plugin): https://da.live/edit?ref={branch-name}#/aemsites/geometrixx/drafts/developer/plugin-demo

For local development, you can use a branch name of local which will send requests to http://localhost:3000.

Notify your users

The best way to notify your users of the fullscreen apps you build is to use Sidekick.

/tools/sidekick/config.json

{
  "project": "Block Collection"
  "apps": [
    {
      "title": "App demo",
      "description": "This is a sample app using the DA SDK.",
      "image": "https://main--da-block-collection--aemsites.hlx.page/media_1061934561e8a4f01907e616a0ce0e4b74d63b92e.jpeg",
      "url": "https://da.live/app/aemsites/da-block-collection/tools/demo-app"
    }
  ]
}

Visit

https://da.live/apps#/aemsites/da-block-collection

At the top of the page you will see a section for the apps you list in Sidekick.

Clone this wiki locally