Embedded Views
The loading mechanism of embedded pages, the initiate signing flow, post-signing redirect, and branding capabilities.
Embedded Page Loading Mechanism
After the integrator application calls the Upload File API to obtain a FileId, it binds the FileId to the webview token via the OperateParam.FileIds field of the Get Embedded View URL API. The embedded page can use it directly upon loading; the integrator does not need to pass the FileId via postMessage. The file corresponding to FileId must be in PDF format; non-PDF files must be converted via the File Convert API first.
The webview token is valid for 12 hours and can be used multiple times within the validity period (multiple page refreshes and API calls within the WebView all use the same token) and is not bound to IP / UA (otherwise mobile devices would fail when switching networks). Request a new one each time you need it; do not cache the webview URL long-term.
Initiate Signing Interaction
Internal APIs such as “create envelope / submit sending” within the embedded page are called by the Tencent eSign frontend; the integrator does not need to care about them. When the integrator application calls the above Open APIs and encounters network / rate limit errors, handle them per Error Handling and Common Return Codes.
OperateType Values
| OperateType | Meaning | Paired OperateParam field |
|---|---|---|
request_signatures | Initiate signing (create envelope) | FileIds (required, array<string>): the list of FileIds available to this embedded page; must be uploaded via the Upload File API, still within the 24-hour validity period, and belonging to the current (user_id, space_id). Files must be in PDF format (non-PDF files must be converted via the File Convert API first) |
signature_status | Contract list | None |
The issued webview token internally binds OperateType and OperateParam: the embedded page can only access the specified resources (e.g., FileIds) within the scope authorized by that token; there is no need to pass them again via postMessage, and unauthorized access is prevented.
Post-Signing Redirect
Sender (within WebView)
The success page provides two actions:
- View Envelope — Open envelope details within the WebView
- Envelope List — Open the contract list within the WebView
Both are in-WebView navigations and do not leave the integrator application.
Signer (recipient opens email link in browser)
The signing success page is displayed per the integrator’s branding configuration:
- Primary button: View in [Integrator App Name] (deep link)
- Secondary button: View Envelope (view in browser)
- Bottom guidance copy
Deep Link Timeout Fallback
Reference implementation:
<a id="open" href="myapp://open-envelope?EnvelopeId=ENV_xxx">View in MyApp</a>
<script>
let opened = false;
document.getElementById('open').addEventListener('click', () => {
setTimeout(() => {
if (!opened) window.location.href = 'https://www.example.com/download';
}, 2000);
});
// Page visibilitychange to hidden → treat as App launched successfully
document.addEventListener('visibilitychange', () => {
if (document.hidden) opened = true;
});
</script>The deep link scheme format and the not-installed fallback URL are submitted by the integrator when creating the OAuth app in the console. See Quickstart - Credential Preparation.
Branding
Customization Items Supported in the Current Version
| Field | Type | Purpose | Default | Format Constraint |
|---|---|---|---|---|
ColorPrimary | string | Embedded page theme color | Use system default theme color | HEX (e.g., #D54941) or RGB (e.g., rgb(213,73,65)) |
ShowFooter | bool | Embedded page footer disclaimer toggle | Show (true) | true (show) / false (hide) |
ShowHeader | bool | Embedded page header toggle | Show (true) | true (show) / false (hide) |
ClientLogo | string | Integrator logo URL (used on OAuth login and authorization pages, does not affect embedded page) | None | HTTPS URL |
Configuration Method
Branding fields are configured by the Tencent eSign R&D team; there is no self-service configuration entry at this time. The integrator submits branding information together when creating the OAuth app in the console, and Tencent eSign loads it into the database to take effect.
Scope of Effect
The customization fields are automatically applied to the embedded page URL returned when calling the Get Embedded View URL API. They do not affect the signing URL (SigningUrl returned by /envelopes/signing-view) or email templates.
The following capabilities are not supported in the current version and will be planned for subsequent releases: brand name, post-signing deep link fallback configuration, and email template branding.
Error Handling
| Scenario | Suggested Handling |
|---|---|
| access_token invalid / expired / revoked | Use refresh_token to exchange for a new one; if refresh_token is also invalid, re-initiate OAuth |
| App has been uninstalled from the Space by the admin | Prompt the user to switch Space or contact the admin to reinstall |
OperateType not in the supported list | Check the value |
OperateParam field missing or mismatched with OperateType | Compare against the OperateType Values table |
FileIds contains a FileId that is not found, expired, or not belonging to the current user | Re-upload the file or check the FileId source |
FileIds file is not in PDF format (OPENAPI.EMBEDDED_FILE_MUST_BE_PDF) | Call the File Convert API to convert the file to PDF, then re-obtain the embedded page URL with the converted FileId |
The HTTP status code of business APIs is uniformly 200. For specific error codes, see Common Return Codes and each API’s detail page. When troubleshooting, please provide the RequestId from the response to Tencent eSign technical support.