Editor Integration Reference

Product Introduction

Aidge Virtual Try-On enables clients to integrate try-on functionality into their own platforms by embedding the following features through an iframe:

• Upload garment images

• Choose your models

• Generate model try-on images

• Manage your design

Integration Preparation

Clients need to obtain credentials

Obtaining Methods

• International Site: https://www.aidge.com/dashboard/api-keys

• Chinese Site: https://cn.aidc-ai.com/dashboard/api-keys

Credentials	Obtaining Methods	Storage Requirements
Name	Aidge Console→ api-keys	Can be Passed Through the Frontend
Key	Aidge Console→ api-keys	Backend Storage, Strictly Prohibit Leakage

Overview of Access Communication Process

Process Description

1. The client-side frontend component requests the client-side backend interface to obtain the parameters required by Aidge.

2. The client-side backend uses the signing method provided by Aidge to generate a signature and returns it along with other parameters to the client-side frontend.

3. The client-side frontend requests the iframe provided by Aidge using the parameter values obtained from the client-side backend.

4. When the client interacts with the Aidge page, there is an interface interaction between Aidge's frontend and backend.

5. The Aidge backend handles tasks like login verification. If verification fails or there is a prolonged period of inactivity, the client is prompted to re-login.

6. When Aidge's frontend needs to interact with the client's frontend, event interactions occur, such as requesting client confirmation for actions or prompting re-login.

Integration Steps (Encryption, Input Parameters, Output Parameters)

Step 1: Client-Side Backend Stores Aidge-Provided Name and Secret

The client obtains the Name and Secret provided by Aidge from the official Aidge platform. The client-side backend securely stores these credentials to generate encrypted signature fields and other parameters required by Aidge.

Step 2: Client-Side Backend Exposes an Interface to Its Frontend

The client-side backend encapsulates an interface (e.g., an HTTP API) for its frontend to generate Aidge-compliant signatures. Using the Name and Secret obtained from Aidge, the backend leverages AidgeSignUtils to generate the required signature. It then returns the parameters (including the signature) to the client-side frontend.

Interface Description

The interface provided by the client-side backend to the client-side frontend must include the following fields in the response:

Parameter	Type	Required	Description
ak	string	Yes	ak applied by the user on the official website
sign	string	Yes	Signature (encrypted using AidgeSignUtils provided by Aidge)
userId	string	Yes	Business-Customized User ID
timeStamp	Long	Yes	Current Unix timestamp (in seconds, e.g., 1739779669 represents February 17, 2025, 16:07:49 UTC). 📢Note: The timeStamp value must remain consistent with the value passed when generating the signature!

Signing Method

Parameter

Parameter	Type	Required	Description
timeStamp	Long	Yes	Current Unix timestamp（in seconds）. 📢Note: The timeStamp must not be ahead or behind; otherwise, the Aidge side will fail the verification and prompt that the login is invalid.
secret	String	Yes	The secret obtained from the Aidge official website. 📢Note: The client-side backend must ensure strict protection against data leakage.
userId	String	No	Client-Defined User ID (used to distinguish between different users within the client-side system). The Aidge platform uses the userId parameter to implement the isolation and sharing of user data (such as generated "history" and used model images). Merchants can choose to pass different userId values or a single unified userId based on their business needs (not passing a userId or passing a fixed userId will have the same effect).

Response parameters:

Type	Description
String	The signed signature. It must be passed through to Aidge's iframe. Aidge will verify the signature; if verification fails, the user will be prompted to log in.

📢 If signature verification fails (including cases where the timeStamp is too far ahead or behind), a prompt indicating that the user is not logged in will be returned.

Signature code:

import javax.crypto.Mac;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Map;
import java.util.TreeMap;

/**
 * Aidge Signing Utility Class
 */
public class AidgeSignUtils {

    private static final char[] HEX_ARRAY = "0123456789ABCDEF".toCharArray();

    /**
     * Generates the signature required for Aidge signing.
     * Note: Use this method to generate the signature if the user ID is not defined on the merchant side, i.e., when the iframe does not pass the userId parameter!
     *
     * @param secret The encryption key (obtained from the Aidge website)
     * @param timeStamp Current Unix timestamp (in seconds), this value must be consistent with the timeStamp passed in the iframe!
     * @return The signed signature
     */
    public static String generateAidgeSign(String secret, Long timeStamp) throws IOException {
        return generateAidgeSign(secret, timeStamp, null);
    }

    /**
     * Generates the signature required for Aidge signing.
     * Note: Use this method to generate the signature if the user ID is defined on the merchant side, i.e., when the iframe passes the userId parameter!
     *
     * @param secret The encryption key (obtained from the Aidge website)
     * @param timeStamp Current Unix timestamp (in seconds), this value must be consistent with the timeStamp passed in the iframe!
     * @param userId Custom user ID defined on the merchant side
     * @return The signed signature
     */
    public static String generateAidgeSign(String secret, Long timeStamp, String userId) throws IOException {
        Map<String, String> params = new TreeMap<>();
        params.put("timeStamp", timeStamp.toString());
        if (userId != null && !userId.trim().isEmpty()) {
            params.put("userId", userId);
        }

        String query = buildQuery(params);
        byte[] bytes = encryptHMACSHA256(query, secret);
        return byte2hex(bytes);
    }

    /**
     * Constructs a sorted query string
     */
    private static String buildQuery(Map<String, String> params) {
        StringBuilder query = new StringBuilder();
        for (Map.Entry<String, String> entry : params.entrySet()) {
            String key = entry.getKey();
            String value = entry.getValue();
            if (isNotEmpty(key) && isNotEmpty(value)) {
                query.append(key).append(value);
            }
        }
        return query.toString();
    }

    /**
     * Checks if a string is non-empty (including whitespace check)
     */
    private static boolean isNotEmpty(String value) {
        if (value == null) return false;
        int length = value.length();
        for (int i = 0; i < length; i++) {
            if (!Character.isWhitespace(value.charAt(i))) {
                return true;
            }
        }
        return false;
    }

    /**
     * HMAC-SHA256 encryption
     */
    private static byte[] encryptHMACSHA256(String data, String secret) throws IOException {
        try {
            SecretKey secretKey = new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256");
            Mac mac = Mac.getInstance(secretKey.getAlgorithm());
            mac.init(secretKey);
            return mac.doFinal(data.getBytes("UTF-8"));
        } catch (GeneralSecurityException e) {
            throw new IOException("Security exception: " + e.getMessage());
        }
    }

    /**
     * Converts byte array to hexadecimal string
     */
    private static String byte2hex(byte[] bytes) {
        if (bytes == null) return "";
        StringBuilder hexString = new StringBuilder(bytes.length * 2);
        for (byte b : bytes) {
            int v = b & 0xFF;
            hexString.append(HEX_ARRAY[v >>> 4]);
            hexString.append(HEX_ARRAY[v & 0x0F]);
        }
        return hexString.toString();
    }

    /**
     * Test code
     */
    public static void main(String[] args) throws IOException {
        String secret = "bPsSEXh136Hp7labcZAGX102crBvdqvi"; 
        Long timeStamp = 1740474548L; 
        String userId = "10001"; 
        String sign = generateAidgeSign(secret, timeStamp, userId);

        // Result: E9CF23C77BF44935246CE5E29510B276335894A7D5DDA868D396AE1B9CDE584A 
        System.out.println(sign); 
    }
}

Step 3: The client-side frontend embeds the iframe provided by Aidge into their own page.

Basic Configuration Embed the iframe into your page:

• For purchasing an AK on the international site: https://manekenai-editor.aidge.com/
• For purchasing an AK on the Chinese site:https://manekenai-editor.aidc-ai.com/

<iframe
  id="maneken-iframe"
  src={`https://manekenai-editor.aidge.com/?ak=xxx&sign=xxx&userId=xxx&timeStamp=xxx`
  style={{ width: "100%", height: "100%", border: "none" }}
  />

URL Parameters

The iframe URL must include the following parameters:

Parameter	Type	Required	Description
ak	string	Yes	API key
sign	string	Yes	Sign
userId	string	Yes	User id
timeStamp	string	Yes	timeStamp
lang	string	No	Language Settings (Default: English) en - English cn - Chinese ja - Japanese

Message Processing

iframe Events

Editor-Emitted Events

Event	Description	Data format
generateConfirm	Generate confirmation event	{ action: "generateConfirm", payload: { suitType, url, isRepaired, refinedVersion, mask, maskArr, modelList, } } suitType-suitType top-top bottoms-bottoms dresses-onepieces suits-suits url-original images mask-RLE data after segment maskArr-Select RLE data through the editor modelList-model list isRepaired-Whether to enable repair refinedVersion-Enhanced repair version 1.0 1.5
save	After the user clicks Save, send the currently input garment images and generation result data.	{ action: "save", payload: { originImageUrls, resultImageId, originImageUrls }} resultImageId - result image id resultImageUrl-result image url originImageUrls-original images
notLogin	Not Logged In Prompt Event	{ action: "notLogin" }
noResource	Insufficient Resources Prompt Event	{ action: "noResource" }
uploadImgUrl	URL After Image Upload	{ action: "uploadImgUrl", payload: { url } } url-image oss
taskResult	Result Event	{ action: "taskResult", payload: { taskId, status, suitType, url, mask, maskArr, modelList, isRepaired, refinedVersion, plannedImageCount, generatedImageCount, planRefinerImageCount, generatedRefinerImageCount, planRepairImageCount, generatedRepairImageCount, result, } } taskId-task id status-task status success-success failed-failed partiallyFailed-partiallyFailed suitType-suitType top-top bottoms-bottoms dresses-onepieces suits-suits url-original images mask-RLE data after segment maskArr-Select RLE data through the editor modelList-model list isRepaired-Whether to enable repair refinedVersion-Enhanced repair version 1.0 1.5 plannedImageCount-planned generation image count generatedImageCount-generated image count planRefinerImageCount-Planned number of virtual try-on pro builds generatedRefinerImageCount-Actual number of virtual try-on pro generated planRepairImageCount-Planned number of hand and foot repairs to be generated generatedRepairImageCount-Actual number of hand and foot repairs generated result-res

ParentPageEventHandling

User page sends an event to the editor.

Event	Description	Data format
generateConfirm	Confirm the generated response.	{ action: "generateConfirm", payload: boolean }

Integration code sample

import { useEffect } from "react";

function IframeComponent() {
  useEffect(() => {
    // Listening for iframe messages
    const handleMessage = (event: MessageEvent) => {
      // Process different types of messages according to action
      switch (event.data.action) {
        case "generateConfirm":
          // Handling build confirmation events
          console.log("Receive build confirmation event:", event.data);
      }
    };

    window.addEventListener("message", handleMessage);
    return () => window.removeEventListener("message", handleMessage);
  }, []);

  return (
    <iframe
      id="maneken-iframe"
      src={`https://manekenai-editor.aidge.com/?ak=xxx&sign=xxx&userId=xxx&timeStamp=xxx`}
        // Online-International Station Purchase AK Use: https://manekenai-editor.aidge.com/
        // Online-Chinese site to buy ak is ing: https://manekenai-editor.aidc-ai.com/
      style={{ width: "100%", height: "100%", border: "none" }}
    />
  );
}