:Embed Smart Q in third-party systems

Background

The ticket-based Smart Q embedding solution provides centralized security control over link generation, access, and queries. Integrate analytics into your business systems and build branded data products at low cost.

Limitations

Only the Professional Edition supports Smart Q embedding.

Before you begin

You have purchased the Smart Q and ticket-based embedding modules.

Smart Q API

The Smart Q API is documented in Intelligent Q&A Embedding.

Examples

• If you embed a dataset By Queryable Resource or embed a single analysis topic, the interface displays all authorized datasets in a flat layout.

  

• If you embed multiple analysis topics using By Analysis Topic, the interface displays datasets under an All tab and under tabs for each analysis topic.

  

Step 1: Create a Smart Q embedding

Create a Smart Q embedding module:

1. On the Quick BI homepage, choose Organization Management > Smart Q > Embedding Management.

2. Click Create Embedded Module, enter an Embedded Module Name, and then click OK.

   

   • Embedded Module Name: identifies the module.

   • Embedded Module Type: defaults to Smart Q (not changeable).

   Note

   Only one embedding module is supported.

3. Configure the Basic Configurations, Agent information, Module appearance, Input guide, and Welcome area sections.

   

   Category	Parameter	Description
   Basic Configurations	Data Scope	Define the data scope By Queryable Resource or By Analysis Topic. Note The data scope is permission-controlled and cannot be previewed. Click Save and Debug Embedding Code to view results on the debugging page. By Queryable Resource By Analysis Topic
   Agent information	Module Name	Custom name. Maximum 20 characters.
   	Agent Nickname	Custom nickname. Maximum 10 characters.
   	Agent Icon	Select Use Stock Image or upload a Custom Image. Note The agent icon appears in the Smart Q area. Custom images: 48x48 px max, PNG or JPG, under 200 KB.
   	Navigation Bar Configuration	Specify whether to Show conversation history in the navigation bar. If selected, past conversations appear in the navigation bar:
   Module appearance	Theme	Select a theme: Smart Light, Smart Dark, or Standard.
   Input guide	Guide Content	Set the guide content to Recommended Questions or None.
   Welcome area	Agent icon	Toggle the agent icon display. If enabled, set the position to Top Center, Top Left, or Left, and adjust the Icon Height.
   	Welcome message	Custom welcome message. Maximum 50 characters:
   	Description	Custom description. Maximum 100 characters:

4. Click OK and Debug Embedding Code. In the Debug Embedding Code dialog box, configure the following parameters.

   

   Parameter	Description
   Ticket URL	Enter a ticket URL or click Quick Generate to create one. On the ticket generation page, set Bind User, Validity Period, and Access Count. Bind User: Binds a specific user's permissions to the embedded content. Validity Period: Expiration time in minutes. Default and maximum: 240 minutes. Access Count: Number of times the URL can be accessed. Default: 1. Maximum: 9,999.
   Get embedding code	Generate a URL or Iframe code for embedding.

5. Click Copy.

Step 2: Generate an AccessTicket

1. Call the create4Copilot API to generate the ticket.

   AccessTicket parameters:

   Parameter	Type	Description
   CopilotId	String	ID of the enabled Smart Q embedding module.
   TicketNum	Integer	Number of times the ticket can be used. Default value: 1. Recommended value: 1. Maximum value: 99,999. Decremented by 1 after each use.
   UserId	String	The user ID in Quick BI (not your Alibaba Cloud account ID). Call the QueryUserInfoByAccount API to obtain the UserId. Example: fe67f61a35a94b7da1a34ba174a7****. Note Specify either UserId or AccountName. If you provide neither, the system uses the permissions of the embedding owner by default.
   AccountName	String	The logon name of the user. Alibaba Cloud account (for example, wangwu): use the format [Alibaba Cloud account], such as wangwu. RAM user (for example, zhangsan**@aliyun.cn): use the format [Alibaba Cloud account]:[RAM user], such as wangwu:zhangsan**. Note Specify either UserId or AccountName. If you provide neither, the system uses the permissions of the embedding owner by default.
   AccountType	Integer	The user account type. 1: Alibaba Cloud account 3: Quick BI local account 4: DingTalk 5: RAM user 9: WeCom 10: Lark Note If you specify AccountName, you must also specify AccountType.
   ExpireTime	Integer	Ticket expiration time in minutes. Unit: minutes. Default: 240.

   Note

   To prevent unauthorized URL sharing, set TicketNum to 1 so that each generated link is single-use.

2. Generate the AccessTicket.

   Code example: CreateTicket4Copilot.

   Sample response:

   { 
     "requestId" : "7D784AB0-5B77-****-B628-E782B58D3898", 
     "result" : "fd138bcb-****-4fde-b413-81bcee59bdb6",
     "success" : true
   }

   Note

   The result field contains the AccessTicket. In this example: fd138bcb-****-4fde-b413-81bcee59bdb6.

Step 3: Construct the logon-free URL

• URL components:

  Component	Example
  1. Quick BI domain	bi.aliyun.com
  2. Smart Q embedding URL path	token3rd/copilot
  3. Smart Q module ID	dd0****83f
  4. AccessTicket	fd138bcb-****-4fde-b413-81bcee59bdb6

• Construct the final URL using this format:

  Format: https://<Quick BI domain>/<Smart Q embedding URL>?copilotId=<Smart Q module ID>&accessTicket=<AccessTicket>

  Example URL: https://bi.aliyun.com/token3rd/copilot?copilotId=dd0****83f&accessTicket=fd138bcb-****-4fde-b413-81bcee59bdb6

• For examples of the embedded display, see Examples.

Embedding management

On the Embedding Management page, edit (①), debug (②), or disable (③) existing modules.

• Click the icon to edit the module.

  Note

  The embedded module name cannot be changed.

  

  After making changes, click Save or Save and Debug Embedding Code to open the debugging interface.

• Click the icon to debug the module.

  

• Click the icon and then click OK in the confirmation dialog box to disable the module.