HyperBridge Theme Integration Guide

[D4vidDf]

This guide details how developers can create themes for HyperBridge and integrate a direct "Apply Theme" button in their own apps (e.g., icon pack dashboards, theme stores, or personalization tools).

1. The Strict Contract

Themes are distributed as HyperBridge Packages (.hbr), which are standard ZIP archives containing a specific folder structure and configuration file. Whether a user downloads the file manually or applies it via your app, the internal structure must be identical.

File Structure

Organize your theme assets as follows before zipping:

my_theme_project
│  
├── theme_config.json        <-- The Brain (Metadata + Rules)  
│  
├── icons/                   <-- Action icons (48x48px PNG suggested)  
│   ├── ic_reply.png  
│   ├── ic_archive.png  
│   └── ic_heart.png  
│  
├── status/                  <-- Progress & Navigation icons  
│   ├── nav_arrow.png  
│   └── download_tick.png  
│  
└── global/                  <-- Backgrounds or overlays (Optional)  
    └── island_glow.png

Note: Once built, rename the .zip file to .hbr (e.g., neon_theme.hbr).

---

2. Configuration (theme_config.json)

The theme_config.json maps your image files to HyperBridge logic.

JSON Specification

{
  "id": "acquatheme",
  "meta": {
    "name": "Neon Cyberpunk",
    "author": "PixelMaster",
    "version": 2,
    "description": "A high contrast neon theme with custom shapes and smart rules."
  },
  "global": {
    "highlight_color": "#00FFDD",
    "background_color": "#202124",
    "text_color": "#FFFFFF",
    "use_app_colors": false,          // If true, dynamic colors from app icon override highlight_color
    "icon_shape_id": "cookie",        // Options: circle, square, squircle, cookie, arch, clover8
    "icon_padding_percent": 15
  },
  "call_config": {
    "answer_color": "#34C759",
    "decline_color": "#FF3B30",
    "answer_shape_id": "circle",      // [NEW] Shape override for answer button
    "decline_shape_id": "circle",     // [NEW] Shape override for decline button
    "answer_icon": {
      "type": "LOCAL_FILE",
      "value": "icons/call_answer.png"
    },
    "decline_icon": {
      "type": "LOCAL_FILE",
      "value": "icons/call_decline.png"
    }
  },
  "default_actions": {
    "reply": {
      "mode": "ICON",                 // Options: ICON, TEXT, BOTH
      "background_color": "#3300FFDD",// Hex color for button background
      "tint_color": "#00FFDD",        // Hex color for icon/text tint
      "icon": {
        "type": "LOCAL_FILE",
        "value": "icons/ic_reply.png"
      }
    },
    "archive": {
      "mode": "ICON",
      "icon": {
        "type": "LOCAL_FILE",
        "value": "icons/ic_archive.png"
      }
    }
  },
  "default_progress": {
    "active_color": "#FF0099",
    "finished_color": "#34C759",
    "show_percentage": true,
    "active_icon": {                  // Icon displayed while progress is running
        "type": "LOCAL_FILE",
        "value": "status/downloading.png"
    },
    "finished_icon": {                // Icon displayed when progress completes
        "type": "LOCAL_FILE",
        "value": "status/download_tick.png"
    }
  },
  "default_navigation": {
    "progress_bar_color": "#00FFDD",
    "swap_sides": false,
    "pic_forward": {
        "type": "LOCAL_FILE",
        "value": "nav/arrow_straight.png"
    },
    "pic_end": {
        "type": "LOCAL_FILE",
        "value": "nav/destination_flag.png"
    }
  },
  "apps": {
    "com.whatsapp": {
      "highlight_color": "#25D366",   // App-specific override
      "actions": {
        "reply": {
          "mode": "BOTH",
          "tint_color": "#FFFFFF",
          "background_color": "#25D366",
          "icon": {
            "type": "LOCAL_FILE",
            "value": "icons/ic_reply_whatsapp.png"
          }
        }
      }
    }
  }
}

---

3. Applying the Theme (Intent Code)

To apply the theme programmatically from your app, you must send the .hbr file via a specific Android Intent. This requires saving the file to your cache (so it is accessible) and sharing it via FileProvider.

Prerequisites

1. File Extension: Ensure the file ends in .hbr or .zip.
2. MIME Type: Use application/zip or application/octet-stream.
3. Permissions: The FLAG_GRANT_READ_URI_PERMISSION is critical.

Kotlin Implementation

Copy this function into your app to handle the "Apply" button click.

import android.content.Context  
import android.content.Intent  
import androidx.core.content.FileProvider  
import java.io.File

fun applyThemeToHyperBridge(context: Context) {  
    try {  
        // 1. Locate your theme file (e.g., copy from assets to cache)  
        // If your theme is in 'assets/neon_theme.hbr':  
        val themeFile = File(context.cacheDir, "neon_theme.hbr")  
          
        if (!themeFile.exists()) {  
            context.assets.open("neon_theme.hbr").use { input ->  
                themeFile.outputStream().use { output -> input.copyTo(output) }  
            }  
        }

        // 2. Create the URI using FileProvider  
        // Ensure you have a FileProvider defined in your AndroidManifest.xml  
        val uri = FileProvider.getUriForFile(  
            context,  
            "${context.packageName}.provider",  
            themeFile  
        )

        // 3. Send the Intent to HyperBridge  
        val intent = Intent("com.d4viddf.hyperbridge.APPLY_THEME").apply {  
            setDataAndType(uri, "application/zip")  
            addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)  
            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)  
        }

        // 4. Launch  
        context.startActivity(intent)

    } catch (e: Exception) {  
        // HyperBridge is likely not installed or the file failed to copy  
        e.printStackTrace()  
        // TODO: Prompt user to install HyperBridge  
    }  
}

Flutter Implementation

For Flutter, use the android_intent_plus package (or similar) to construct the specific intent.

import 'dart:io';  
import 'package:android_intent_plus/android_intent.dart';  
import 'package:path_provider/path_provider.dart';  
// Note: You must handle copying the asset to a file path first.

Future<void> applyTheme() async {  
  // 1. Get the path to your .hbr file (e.g., from temporary directory)  
  final dir = await getTemporaryDirectory();  
  final filePath = '${dir.path}/neon_theme.hbr';  
    
  // (Ensure file exists at filePath...)

  // 2. Create the Intent  
  // Note: Flutter's ability to grant URI permissions directly is limited compared to native.  
  // Using 'action_view' is often more reliable for cross-app file opening in Flutter.  
  final intent = AndroidIntent(  
    action: 'com.d4viddf.hyperbridge.APPLY_THEME',  
    type: 'application/zip',  
    data: Uri.parse('content://$filePath').toString(), // This often requires a platform channel for proper FileProvider URI  
    flags: <int>[  
      0x00000001, // FLAG_GRANT_READ_URI_PERMISSION  
      0x10000000, // FLAG_ACTIVITY_NEW_TASK  
    ],  
  );

  await intent.launch();  
}

Note: For complex file sharing in Flutter (generating a content:// URI), it is highly recommended to use a native MethodChannel that implements the Kotlin code above.

---

4. Summary of the Public API

Component	Specification
Structure	Folder with theme_config.json + icons/ folder.
Package	ZIP format, renamed to .hbr.
Intent Action	com.d4viddf.hyperbridge.APPLY_THEME
Data Type	application/zip
Security	Requires FileProvider URI + Read Permission Flag.

This format is universal. A .hbr file created for this intent can also be uploaded to Telegram, Discord, or Google Drive for users to install manually via the HyperBridge "Import" menu.

[m4lican]

Hello Do you have any paid and more useful themes?
And I want to reply via notification, I can't send a reply from the island.

[D4vidDf]

Hello,
Right now there's no paid themes available, in the future there will be new themes available.

Unfortunately, Xiaomi blocks the respond functionality in the island. Xiaomi it's working on adding new functionalities in the next HyperOS updates.

[renanhipolito]

Olá! Este alguma configuração que faça a ilha dinâmica ficar fixa aparecendo? Com notificação ou não ela fique ali aparecendo igual no iPhone.

[m4lican]

It would be great if more of the notification content were visible.

[D4vidDf]

Xiaomi limits the number of characters on the notification. In the future there would be an option to use a custom RV (Remote Views).

This will let you personalize how you want the notification to look and also show more information.

[javan-michael]

Hi, is there a way to change the colour of the island entirely because when I change the theme colour it only shows like a ring of the colour around the island notification although I have the use_app_colors variable at false. Or also could this be because of device constraints?

[D4vidDf]

the color is for the highlight that xiaomi uses on the island.

Xiaomi doesnt offer the option to change the color of the island itslef, only the content like progres, highlighted text and the highlight color around the islan.

Xiaomi is actively improving the island so we might get more customization options in the future since we have light and darkerparameters for the island, but right now only the darker mode is being use even if you have your phone on light mode

[RockyAnXpert]

Few example themes would have been better

[alejandroisaacjm17-sketch]

Hola, está actualización que incluye la isla dinámica, es genial aunque seria mejor que la isla quedará fija como si fuera una notch.