Build with Joonweb | Developer Documentation

File structure #

App blocks for themes #

Apps that inject inline content on a page extend themes using app blocks. Merchants can add app blocks to a compatible theme section, or as app blocks that are added at the section level. Create an app block by setting the `target` in the schema to `section`.

By default, themes don't include app blocks after an app is installed. Merchants need to add the app blocks to the theme from the **Apps**

### Example app block

The following example creates a `span` element with a `style` attribute. The `style` value (`color: {{ block.settings.color }}`) searches inside of `schema` for a `settings` key, and then searches for a `color` key, which contains the `"default": "#000000"` value. This value then populates the `style` attribute with the default color `#000000`, which renders the `App blocks let you build powerful integrations with online store themes!` text in black.

## Example app block

```jw
<div class="jw-announcement-banner" style="
    background-color: {{ section.settings.bg_color }};
    color: {{ section.settings.text_color }};
    padding: {{ section.settings.padding }}px 20px;
    text-align: {{ section.settings.alignment }};
">
    <h3 style="margin: 0;">{{ section.settings.heading }}</h3>
    
    {% if section.settings.show_button and section.settings.button_link %}
        <a href="{{ section.settings.button_link }}" style="color: {{ section.settings.text_color }};">
            Learn More
        </a>
    {% endif %}

{% rules %}
{
  "name": "Announcement Banner",
  "settings": [
    {
      "type": "header",
      "content": "Text Configuration"
    },
    {
      "type": "text",
      "id": "heading",
      "label": "Banner Heading",
      "default": "Welcome to our store!"
    },
    {
      "type": "select",
      "id": "alignment",
      "label": "Text Alignment",
      "options": [
        { "label": "Left", "value": "left" },
        { "label": "Center", "value": "center" },
        { "label": "Right", "value": "right" }
      ],
      "default": "center"
    },
    {
      "type": "header",
      "content": "Design & Colors"
    },
    {
      "type": "color",
      "id": "bg_color",
      "label": "Background Color",
      "default": "#4f46e5"
    },
    {
      "type": "color",
      "id": "text_color",
      "label": "Text Color",
      "default": "#ffffff"
    },
    {
      "type": "range",
      "id": "padding",
      "label": "Vertical Padding",
      "min": 10,
      "max": 100,
      "step": 5,
      "unit": "px",
      "default": 20
    },
    {
      "type": "header",
      "content": "Action Button"
    },
    {
      "type": "checkbox",
      "id": "show_button",
      "label": "Enable Button",
      "default": false
    },
    {
      "type": "url",
      "id": "button_link",
      "label": "Button Link"
    }
  ]
}
{% endrules %}

```

App embed blocks #

Apps that don't have a UI component, or that add floating or overlaid elements, extend themes using app embed blocks. Joonweb renders and injects app embed blocks before HTML `</head>` and `</body>` closing tags. Create an app embed block by setting the `target` in the schema to either `compliance_head`, `head`, or `body`. App embed blocks with `compliance_head` will be included first and should be used only when necessary, for example in cookie consent banners.

By default, app embed blocks are deactivated after an app is installed. Merchants need to activate app embed blocks in the theme editor, from **Theme Settings** > **App embeds**. However, your app can provide merchants with a deeplink, post installation, to activate an app embed block automatically.

**Use app embed blocks for the following types of apps:
**

* Apps that provide a floating or overlaid component to a page, such as chat bubble apps and product image badge apps.

* Apps that add SEO meta tags, analytics, or tracking pixels.

## Example app embed block

```jw
<div style={{position: 'fixed', bottom: '0', right: '0'}}>
    {{ "float.jpg" | asset_url | img_tag }}
</div>
{% rules %}
  {
    "name": "App Embed",
    "target": "body",
    "settings": []
  }
{% endrules %}
```

Rules #

The rules for app blocks and app embed blocks supports the following attributes, some of which are unique to app blocks and app embed blocks:

| Attribute | Description | Required |
| - | - | - |
| `name` | The title in the theme editor for the app block or app embed block.Keep app block and app embed block names under 25 characters so they fit in the theme editor sidebar.Don't include the title of your app in the name of the block. The title of your app displays below the name of the app block or app embed block in app block pickers, the app embeds panel, and the app details panel. | Yes |
| `target` | Where the block is located. The possible values are `section`, `head`, `compliance_head`, and `body`.The value for app blocks is `section`. The values for app embed blocks are `head`, `compliance_head`, and `body`. | Yes |
| `JavaScript` | A JavaScript file to load from the `assets` subdirectory.If the block is present on the page, then you can load this file automatically by adding a `<script async>` tag in the `<head>` section of the page.If a merchant adds multiple app blocks or app embed blocks that reference the same JavaScript file to a page, then the file is only included once when the page is loaded. | No |
| `stylesheet` | A CSS file to load from the `assets` subdirectory.If the block is present on the page, then you can load this file automatically by adding a `<link rel="stylesheet">` tag in the `<head>` section of the page.If a merchant adds multiple app blocks or app embed blocks that reference the same stylesheet file to a page, then the file is only included once when the page is loaded. | No |
| `enabled_on` | Limit an app block to specific templates and section groups, or limit an app embed block to specific templates. App blocks and app embed blocks can't be rendered on checkout pages, you can use only one of `enabled_on` or `disabled_on`. | No |
| `disabled_on` | Prevent app block from being used in specific templates and section groups, or prevent an app embed block from being used in specific templates.App blocks and app embed blocks. You can use only one of `enabled_on` or `disabled_on`. | No |
| `class` | Additional CSS classes to be included in the wrapping tag element. Theme app extensions will always include the `joonweb-block` class. | No |
| `tag` | If set, then a tag wraps the block's output. If not set, then the output is wrapped in a `div`. | No |
| `settings` |  that you provide to the merchant for customizing the app block or app embed block. These settings appear in the theme editor when the block is selected. Setting values can be using the jw object. | No |
| `default` | A default setting configuration for the block. | No |

Deep linking #

Post-installation, your app can provide deep links to help merchants add app blocks or activate app embed blocks directly in a theme. If a merchant clicks a deep link, then they're taken to the builder to preview the app block or app embed block before saving.

Deep linking ease your app's installation because merchants won't need to navigate to the builder or code editor, find the block, and then act on it. Instead, your app does the work for them. Merchants can preview the block before saving and have more control over what they include in their online store.

#### App block deep linking

**You can implement a deep link to add an app block to the following locations:
**
* Any JSON template. For example, the `Default product` template.

* Any main section that supports app blocks. For example, the `product-detail` section.

After you add the app block in the builder, you can navigate to setting if you have configured in rules.
	
	 **Note:**

You can deep link only to sections, pages that support app blocks. Additionally, you can add only one app block at a time with a deep link.

#### App block deep link query parameters

| Query parameter | Description |
  | - | - |
  | `{target_page}` | The JSON template to which the app block should be added. If not set, then Shopify will default to the index.json template. |
  | `{ext_uuid}` | The ID of the theme app extension block. |
  | `{ext_block}` | The filename of the block's jw file.For example, if the jw file is located at `theme-app-extension/blocks/app-block.jw`, then the `{ext_block}` is `app-block`.|

#### Example URLs

Your app needs to redirect merchants to a URL with populated parameters.

**Adding an app block to any Supported Page**

The following is the deep link structure for adding an app block to any  page in a new Apps section:

## App block URL

```text
https://accounts.joonweb.com/site/builder/?target_page=${target_page}&add_extension={api_key}/{handle}
```

For example, the deep link to add the `my_floating.jw` block

## Adding my\_floating block:

```text
add_extension=7e24ff92-9362-4765-8909-bdb2905f001f/my_floating
```

#### App embed block deep linking

You can implement a deep link to activate an app embed block directly in a theme.

#### App embed block deep link URL query parameters

| Query parameter | Description |
| - | - |
| `{extension_uid}` | The context in which the app is being activated. The value is `apps`. |
| `{block_handle}` | The filename of the block's JW file.For example, if the JW file is located at `theme-app-extension/blocks/app-embed.jw`, then the `{block_handle}` is `app-embed`.To see this Liquid file in the context of an app embed block, refer to the theme app extension |

#### App embed block deep linking URL

Your app needs to redirect merchants to the following URL, with URL query parameters populated:

## App embed block URL

```url
https://accounts.joonweb.com/site/builder/?activate_extension={ext_uuid}/{ext_block}
```

Detected If Embeded App is installed or not #

This guide explains how to fetch a JoonWeb store's active theme configuration via the Admin API and verify if a specific App or Block is currently **installed** and **enabled**.

---

## 📋 Prerequisites

Before making the API call, ensure you have:
1. **JoonWeb Admin API Token:** Required to authenticate your API request.
2. **Site URL (`siteUrl`):** The specific subdomain for the target JoonWeb store (e.g., `yoursiteurl`).

---

## 🚀 Step-by-Step Guide

### 1. Fetch the Theme Configuration
Make a `GET` request to the Asset API to retrieve the `theme_config.json` file from the currently active theme.

**Endpoint:**
```http
GET https://{yoursiteurl}.myjoonweb.com/api/admin/26.0/themes/current/assets/file?key=theme_config.json
```

**Expected JSON Response:**
```json
{
  "asset": {
    "key": "theme_config.json",
    "content": "{\"blocks\": {...}}" 
  }
}
```

### 2. Decode the Content
The `content` property is returned as a stringified JSON object. You need to parse the initial response, and then parse the `content` string to access the theme's blocks.

```javascript
const data = await res.json();
const config = JSON.parse(data.asset.content);

// Extract the blocks object
const blocks = config.blocks || {};
```

### 3. Verify Installation Status
Initialize your state variables. You can check for installation using either your **App Handle** or your specific **Block Name**.

```javascript
let isInstalled = false;
let isEnabled = false;
```

#### Method A: Checking via App Handle
Use this method to verify if *any* block associated with your specific app handle is present.

```javascript
const APP_HANDLE = "my-app"; // Replace with your app handle

for (const id in blocks) {
  const block = blocks[id];
  if (block.type === "apps" && block.src.includes(`/apps/${APP_HANDLE}/`)) {
    isInstalled = true;
    isEnabled = block.enabled === true;
    break; // Exit loop once found
  }
}
```

#### Method B: Checking via Block Name
Use this method to verify a specific block file (excluding the `.jw` extension).

```javascript
const block_name = "my-block_file"; // Replace with your block file name

for (const id in blocks) {
  const block = blocks[id];
  if (block.type === "apps" && block.src.includes(`/blocks/${block_name}/`)) {
    isInstalled = true;
    isEnabled = block.enabled === true;
    break; // Exit loop once found
  }
}
```

---

## 💻 Complete Integration Example

Here is a complete, reusable asynchronous function that puts everything together:

```javascript
/**
 * Checks if a specific app or block is installed and enabled on the current theme.
 * @param {string} siteUrl - The store's subdomain (e.g., 'mystore')
 * @param {string} apiToken - The Admin API access token
 * @param {string} target - The App Handle or Block Name to check
 * @param {string} checkType - Set to 'app' or 'block'
 * @returns {Promise<{isInstalled: boolean, isEnabled: boolean}>}
 */
async function checkInstallationStatus(siteUrl, apiToken, target, checkType = 'app') {
  try {
    const url = `https://${siteUrl}.myjoonweb.com/api/admin/26.0/themes/current/assets/file?key=theme_config.json`;
    
    // 1. Fetch the asset
    const res = await fetch(url, {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiToken}` // Adjust header if JoonWeb requires a different token format
      }
    });

if (!res.ok) throw new Error(`API returned status: ${res.status}`);

// 2. Parse the response and the nested content string
    const data = await res.json();
    const config = JSON.parse(data.asset.content);
    const blocks = config.blocks || {};

let isInstalled = false;
    let isEnabled = false;

// 3. Check for installation based on type
    for (const id in blocks) {
      const block = blocks[id];
      
      if (block.type === "apps") {
        const isMatch = checkType === 'app' 
          ? block.src.includes(`/apps/${target}/`)
          : block.src.includes(`/blocks/${target}/`);

if (isMatch) {
          isInstalled = true;
          isEnabled = block.enabled === true;
          break; // Exit loop once found
        }
      }
    }

console.log({ target, isInstalled, isEnabled });
    return { isInstalled, isEnabled };

} catch (error) {
    console.error("Error fetching theme config:", error);
    return { isInstalled: false, isEnabled: false };
  }
}

// Example Usage:
// checkInstallationStatus('mystore', 'your-api-token-here', 'my-app', 'app');
```

**Note: Make sure to call this in backend so it will not expose your auth token.**