Third-Party App
Hardware Access and Credits Redemption
Integration Introduction
Platform Overview
WorkBuddy Open Platform uses the OAuth 2.1 specification for user authentication and authorization, and provides HTTPS-based Open APIs for developers and ecosystem partners. Third-party applications can operate on user data through the Open API after obtaining user authorization.
To protect the security and privacy of user data, third-party applications must explicitly request authorization from the user before accessing user data. After the user authorizes, the platform issues third-party credentials in accordance with the OAuth specification. Third-party applications can obtain these credentials and perform the required operations with the platform.
Core Capabilities
| Capability Domain | Description |
|---|---|
| Local Assistant Chat | Message interaction with the PC local assistant via API |
| Cloud Task Management | Create and manage cloud AI tasks; supports mobile / app sessions |
| Artifact Management | Fetch session artifacts, incremental updates, and media file downloads |
| Redemption Code Redemption | Redeem WorkBuddy credits for users via vouchers or redemption codes |
Application Types
The Open Platform currently supports two types of third-party applications for different integration scenarios:
| Application Type | Description | Available Permissions |
|---|---|---|
| Hardware Access | Open API capabilities for hardware device vendors and partners. Hardware devices (such as smart glasses and in-vehicle systems) connect to WorkBuddy through the Open Platform. After user authorization, they can call Open APIs such as local assistant chat, cloud tasks, and session artifacts | All permissions (apply as needed for the business) |
| Credits Redemption | Credit-benefits API capabilities for developers and partners. After user authorization, the application can redeem WorkBuddy credits for users via vouchers or redemption codes, suitable for credit issuance and similar scenarios | Partial permissions (e.g. credits and benefits) |
Terminology
| Role | Description | Trust Boundary |
|---|---|---|
| Resource Owner | The resource owner, typically a WorkBuddy user | Determines the resource scope accessible to third-party apps or connectors |
| Third Application | A standard third-party application built on WorkBuddy Open Platform | Can call Open API after user authorization |
| WorkBuddy | The agent runtime that executes tasks and initiates tool calls on behalf of the user | Short-lived credentials should be obtained before calling |
| Open Platform | The open platform responsible for app registration, authorization confirmation, token issuance, Scope management, and auditing | Platform-level trust boundary; the permission source for all open API calls |
Integration Guide
Integration Flow Overview
Step 1: Create an Application and Complete Configuration
In WorkBuddy Open Platform, fill in the application basic information, permission management information, and callback URL configuration in one pass. After completing all application configuration, submit for review.
Step 2: From User Authorization to Calling APIs
The application guides the user through OAuth 2.1 authorization. After the server exchanges for access credentials, it can call the Open API. The overall process consists of three consecutive stages:
- First, the third-party application initiates user authorization
- After the user completes authorization, the application server exchanges for access credentials
- The application uses the access credentials to call the required Open API
For details on authorization requests, see "Auth API: Request User Authorization". For obtaining and refreshing access credentials, see "Auth API: Exchange for Access Credentials". For parameters, permissions, and response structures of specific business APIs, see "Open API Reference". The following sequence diagram shows the complete process from user authorization to API calls.
Application Registration and Authorization
Hardware Access
Hardware Access is open to hardware device vendors and partners. After creating a hardware access application on the Open Platform, hardware devices (such as smart glasses and in-vehicle systems) can complete OAuth 2.1 authorization with the user and then use Open APIs for local assistant chat, cloud task management, session artifacts, and more, extending WorkBuddy's agent capabilities to hardware terminals.
When creating a hardware access application, complete the basic information, permission management information, and callback URL configuration in one pass. After submission, the application enters the review process. Once approved, the application is published and the corresponding capabilities are enabled.
Application Basic Configuration
- Sign in to WorkBuddy Open Platform
- Click "Hardware Access"
- Fill in the basic information
- Configure permission management information
- Configure the OAuth callback URL
- Submit for review
Credits Redemption
The Credits Redemption application is open to developers and partners for credit-benefits redemption. After user authorization, the application can use Open APIs to redeem WorkBuddy credits for users via vouchers or redemption codes, suitable for credit issuance and similar scenarios.
When creating a Credits Redemption application, complete the basic information, permission management information, and callback URL configuration in one pass. After submission, the application enters the review process. Once approved, the application is published and the corresponding capabilities are enabled.
Application Basic Configuration
- Sign in to WorkBuddy Open Platform
- Click "Other > Credits"
- Fill in the basic information
- Configure permission management information (only credits and benefits Scopes are available)
- Configure the OAuth callback URL
- Submit for review
Application Notes
| Status | Description |
|---|---|
| Under Review | Application configuration submitted; awaiting platform review |
| Enabled | Application approved and published; can call authorized Open APIs |
| Rejected | Application review failed; modify the configuration based on review feedback and resubmit |
Application credential notes: After creation, the application enters review status and the platform generates client_id and client_secret. client_secret is shown in plaintext only once after the application is created successfully. Keep client_secret secure and do not expose it in frontend or client code. If it is lost, contact the platform.
Authorization
After the application is approved and enabled, guide the user through OAuth 2.1 authorization to obtain an access_token. The authorization flow involves two types of endpoints. Full API documentation is in "Open API Reference":
- "Auth API" — GET /authorize (request user authorization), POST /token (exchange / refresh Token)
Token Types Overview
| Token Type | Purpose | Validity | Notes |
|---|---|---|---|
| access_token | Credential for calling Open API | 24 hours | Obtained via "Exchange for Access Credentials"; must be re-obtained after expiration. |
| refresh_token | Refresh access_token | 60 days | Obtained via "Exchange for Access Credentials"; must be stored securely on the server and must not be exposed in frontend or client code. |
Permission Configuration
Scope Permission List
| Category | Scope | Permission Name | Description |
|---|---|---|---|
| User profile | user.profile.readable | Read personal profile | Read the user's nickname and avatar |
| User profile | user.contact.readable | Verify contact information | Check whether the phone number provided by the caller matches the user's phone number |
| Credits and benefits | user.credit.exchange | Redeem credits via voucher | Redeem WorkBuddy credits for the user via a voucher or redemption code |
| Cloud tasks | user.task.invokable | Create and execute cloud tasks | Allow the application to create and execute cloud tasks per user instructions |
| Cloud tasks | user.task.readable | Read task list and details | Allow the application to read the user's cloud task list and task details |
| Local assistant | user.localassistant.invokable | Send messages to the local assistant | Send messages to the local assistant (the user's PC) to drive the on-device Agent to execute tasks |
| Local assistant | user.localassistant.readable | Read local assistant online status and message history | Read the local assistant's (user PC) online status and conversation message history |
Permission Application Guide
Application Steps
- On the application management page, select the Scope to apply for
- Describe the use case and necessity
- Submit for review
Available Scopes vary by application type: hardware-access applications can apply for all Scopes as their business requires, while credits-redemption applications expose only a subset of permissions (such as the credits and benefits scope user.credit.exchange) and offer no options from other capability domains.
Principle of least privilege: Apply only for Scopes required by the application's features; when the user authorizes, request only the Scopes needed for the current operation; avoid requesting permissions beyond business needs.
Share Capability Integration
Feature Overview
WorkBuddy Share lets a third-party application send text, images, audio, files, and resource links into WorkBuddy in one step.
WorkBuddy Share is open to developers who have completed enterprise verification. Register a share application on WorkBuddy Open Platform (fill in Basic configuration → App platform information), submit it for review, and an application ID is generated. After approval, generate a key pair to obtain share integration permission.
WorkBuddy Share supports PC (Windows / macOS) and mobile (Android / iOS / HarmonyOS) integration.
Before You Integrate
Before integrating the share capability, register a share application on WorkBuddy Open Platform, pass review, and generate a key pair. Confirm that the user's WorkBuddy client is 5.8.0 or later. Earlier versions cannot launch a share.
On the Open Platform, open Third-party integration → Share capability integration, click Register application, and complete the two steps Basic configuration → App platform information. You can Save draft at any time. An application ID is generated as soon as you submit for review, and the review finishes within 7 business days. After approval, generate a key pair on the application details page, then integrate by following the Development Guide.
Step 1: Basic Configuration
| Field | Required | How to fill it in |
|---|---|---|
| Application name | Yes | Unique across the platform. A duplicate name cannot be submitted. Use the real product name, consistent with the application website. Do not use words such as "Demo", "test", or "测试". Exaggerated, misleading, or infringing names are not allowed |
| Application logo | Yes | At least 96×96 px, at most 100 KB, JPG or PNG. Use the product's real icon. Do not use unauthorized third-party assets |
| Application description | Yes | Describe the service and features the application provides. Reviewers use this to verify that the application is real, and it must match the actual features |
| Application website | Yes | Must be reachable (a login page does not count). The page must include an application introduction, service details, a user agreement, copyright information, and website filing information. Applications whose filing entity matches the verified entity on the Open Platform are approved first. If they differ, explain the relationship in the application notes |
| Application notes | No | Anything reviewers need to know, such as a login account for viewing the website or an explanation of the relationship between entities |
Step 2: App Platform Information
Select the platforms to integrate. Select at least one. Each selected platform expands into its own card.
Windows application
| Field | Required | How to fill it in and where to find it |
|---|---|---|
| Windows application identifier | Yes | The executable file name of the main program (for example wemeet.exe) or the product name. Windows has no package-name concept. Do not enter a reverse-DNS name |
| Code signing subject | Yes | The Subject of the signing certificate. To find it: right-click the .exe → Properties → Digital Signatures → select the signature → Details → View Certificate → Subject |
| Code signing certificate thumbprint | Yes | The certificate Thumbprint, 40 hexadecimal characters. Find it on the same path under Thumbprint. The thumbprint shown in certificate properties has a space between every two characters. Remove the spaces when you fill it in |
| Application listed | Yes | Yes / No. If you select Yes, provide a download link (Microsoft Store or the official website) |
| Integration method | Fixed | deeplink |
Read the subject and thumbprint together (PowerShell; replace the path with your exe path):
$sig = Get-AuthenticodeSignature "C:\Path\To\App.exe"
$sig.SignerCertificate.Subject # 例:CN="XXX Technology Co., Ltd.", O="XXX Technology Co., Ltd.", C=CN
$sig.SignerCertificate.Thumbprint # 例:A1B2C3D4E5F6…(40 位十六进制)
The application must be published with a code signing certificate (OV / EV certificates require a verified company application). Self-signed or unsigned applications cannot pass review.
macOS application
| Field | Required | How to fill it in and where to find it |
|---|---|---|
| Bundle ID | Yes | The unique identifier of your macOS application. Find it in the Xcode project under General → Identity → Bundle Identifier |
| Team ID | Yes | The 10-character identifier Apple assigns to a developer team. Sign in to developer.apple.com → Account → Membership details |
| Application listed | Yes | Yes / No. If you select Yes, provide a download link (Mac App Store or the official website) |
| Integration method | Fixed | deeplink |
Read the Bundle ID and Team ID together (Terminal; replace the path with your .app path):
defaults read /Applications/你的应用.app/Contents/Info.plist CFBundleIdentifier # 例:com.example.app
codesign -dv --verbose=4 /Applications/你的应用.app 2>&1 | grep TeamIdentifier # 例:TeamIdentifier=AB12CD34EF
The Team ID comes from the Apple Developer Program membership page and is shared by every application in the same team. If you cannot see it, confirm that the account has joined the developer program.
What these fields are for: Launching on desktop does not verify the caller's application signature. The Windows code signing subject and thumbprint, and the macOS Team ID, are used for registration, uniqueness checks, and review. A wrong value does not block launch, but it is rejected during review.
iOS Application
| Field | Required | How to fill it in |
|---|---|---|
| Bundle ID | Yes | Unique identifier of the iPhone application |
| Test Bundle ID | No | Bundle ID of the iPhone application's test build |
| Universal Links | Yes | A Universal Links path that can launch this application. It must start with https and end with /. Including a path is recommended. The SDK checks that it matches when called |
| Application listed | Yes | Yes / No. If you select Yes, enter an App Store link, for example https://apps.apple.com/cn/app/xxx?id120834128 |
| Integration method | Fixed | SDK |
Android Application
| Field | Required | How to fill it in |
|---|---|---|
| Application signature | Yes | Used to verify the application's identity a second time. Read it with a signature tool from a phone that has the application installed. It is determined by the keystore that signed the application. See https://www.workbuddy.cn/space/d/49f1C4ZNnv0mDwQZ5y4sEI |
| Package name | Yes | The unique identifier of the application on a device, declared in the manifest. It must match the package name of the release build |
| Application listed | Yes | Yes / No. If you select Yes, enter a Google Play or other Android store link. A direct APK download URL is not allowed. At most 256 bytes |
| Copyright certificate | Yes | Computer software copyright certificate. Up to 3 images, jpg / png / jpeg, each no larger than 5 MB |
| Store screenshots | Yes | Must include the application name, package name, and signature. Up to 3 images, in the same format and size as above |
| Integration method | Fixed | SDK |
HarmonyOS Application
| Field | Required | How to fill it in |
|---|---|---|
| Bundle ID | Yes | HarmonyOS application package name. See the Huawei documentation |
| identifier | Yes | The HarmonyOS application's appIdentifier, used as the unique identifier of the application. See the Huawei documentation |
| Application listed | Yes | Yes / No |
| Application name | Yes | The application name in the HarmonyOS AppGallery. This name must be enough to search for and download the application. At most 256 bytes |
| Copyright certificate | Yes | Computer software copyright certificate. Up to 3 images, jpg / png / jpeg, each no larger than 5 MB |
| Store screenshots | Yes | Must include the application name, package name, and signature. Up to 3 images, in the same format and size as above |
| Integration method | Fixed | SDK |
What the mobile fields are for: When the SDK starts a share, WorkBuddy compares the Bundle ID or package name, the appIdentifier, and the application signature with the registered values. If they do not match, the share is rejected. Universal Links are used to check that the launch path comes from the registered application.
Submission and Review
After both steps are complete, click Submit for review.
| Item | Description |
|---|---|
| Submit | The submit button stays disabled while a required field is missing |
| Application ID | Generated immediately after submission. The application status becomes Under review. You can view the application ID, but you cannot generate a key pair yet |
| Review | Completed within 7 business days. During review you can Withdraw the application and return to editing |
| Result notification | The result is sent through the Open Platform notification center, the in-app WorkBuddy message center, and the developer email. A rejection includes the reason. You can edit and resubmit, and the application ID stays the same |
| After approval | The application status becomes Enabled. Generate a key pair under Security configuration on the application details page, then integrate the share capability by following the Development Guide. Basic information is frozen after submission. The platform handles later changes. You can Add a platform at any time |
Generate a Key Pair
The key pair is generated after the application is approved. It is not submitted when the application is created.
| Item | Description |
|---|---|
| Where to generate | On the application details page, click Generate a key pair. Only the organization's super admin can do this |
| How it is generated | An asymmetric key pair is generated locally in the browser (RSA-2048, private key in PKCS#8 PEM, signature algorithm RSAwithSHA256 with PSS padding). The private key never reaches the platform server |
| Key ID | After generation, the key pair's identifier kid is shown. Pass it with the signature parameters when calling the share capability. WorkBuddy looks up the matching public key by kid to verify the signature |
| When it takes effect | It takes effect as soon as it is generated. No extra save step is required. The public key is used for verification immediately |
| Keeping the private key | A dialog shows the public key and the private key. The private key can be copied in one click, with the notice "The private key is shown only this once. It will not be shown again after you close this dialog. Copy and save it now." After the dialog closes, the private key is not shown again. The platform does not store your private key. If you lose it, generate a new pair. Keep the private key on your server. Do not put it in a web page, a desktop application package, or a mobile application package |
| Limit | At most 10 key pairs can be active at the same time. At the limit, delete a key pair you no longer use before generating another |
| Multiple pairs | Several pairs can be active at once, each with its own kid. WorkBuddy selects the public key by the kid sent with the call, so you can rotate smoothly: generate the new pair, switch signing to the new kid, then delete the old pair |
| Delete | You can delete a key pair you no longer use. Deletion takes effect immediately, and that public key is no longer used for verification. The kid becomes invalid, and calls still signed with the old kid fail verification |
| Public key | The key list shows each kid, the public key fingerprint, the creation time, and the last-used time. The public key can be copied at any time. The private key appears only once, in the generation dialog |
Identifier Conflicts and Appeals
| Check | Rule |
|---|---|
| Application name | Unique across the platform. A duplicate shows "该应用名称已被占用,请更换" under the input |
| Per-platform application identifier and signature information | Unique across the platform for that platform, and it can belong to only one organization. A conflict is blocked and an appeal is offered |
To appeal: if the identifier or name is yours (for example after a rebind, or when another account claimed it by mistake), email openworkbuddy@tencent.com. Include the occupied application name or identifier, your developer organization name, and proof of ownership (a software copyright certificate, screenshots of a store console, and similar). The platform checks the verified organization and then updates ownership.
Using the WorkBuddy Brand Mark
After you integrate the share capability, show the WorkBuddy mark on the entry in your application that launches a share (the share target in the share panel, and the integration badge on the settings page), so users can see where the content will go. The mark must follow the WorkBuddy brand guidelines: WorkBuddy Brand Center (switch to the WorkBuddy brand after you open it, and download logo assets from 徽标 on that page).
| Category | Rule |
|---|---|
| Where it may be used | Only on entries directly related to the WorkBuddy share capability. Do not use it as your application icon, splash screen, advertising, or external promotional material |
| Assets | Use the official logo pack downloaded from the brand center, or the standard assets provided by the SDK. Use them as-is. You may scale them proportionally. Do not stretch, squash, crop, rotate, or add shadows or effects |
| Clear space and background | Keep the required clear space. On a light background use the standard horizontal lockup or the symbol. On a dark background the wordmark turns white, but the symbol stays the brand color. Do not place it on a busy background |
| Color | Do not change the specified colors of the logo or the symbol, and do not use unapproved colors |
| Visual hierarchy | The WorkBuddy mark must not be more visually prominent than your own brand |
| Wording | Always write WorkBuddy (camel case). Do not write WORK BUDDY, Work Buddy, or codebuddy. Describe it as "分享到 WorkBuddy" or "基于 WorkBuddy". Do not use wording such as "官方", "授权", or "合作伙伴" |
| What the relationship means | Showing the WorkBuddy mark only means you have integrated the share capability. It does not mean WorkBuddy officially endorses or recommends you |
The platform checks mark usage during application review and in production. If the mark is not used as specified, the platform may require a correction and pause the share capability.
FAQ
| Question | Answer |
|---|---|
| The certificate thumbprint is rejected as the wrong format | The thumbprint in the certificate properties has a space between every two characters. Remove the spaces. It is 40 hexadecimal characters |
| The signing subject or thumbprint cannot be read | Confirm the exe is signed with a code signing certificate. If Properties has no Digital Signatures tab, the file is unsigned, and an unsigned application cannot integrate |
| The Team ID cannot be found | Sign in to developer.apple.com → Account → Membership details. The account must have joined the Apple Developer Program |
| Several products in one company share one signing certificate | They can integrate. Create a separate application for each product and fill in that product's application identifier |
| The application is not listed in any store yet | It can still integrate. Set Application listed to No. After it is listed, add the link on the application details page |
| There is no code signing certificate | Windows cannot integrate yet. Apply for an OV / EV code signing certificate, then submit |
| The private key was lost | Generate a new key pair under Security configuration on the application details page. It takes effect immediately. Delete the old key pair once you are sure it is no longer used |
| Android share returns unavailable or verification fails | Check that the package name and application signature match the installed package. Debug and Release signatures differ and must both be registered. If a store re-signs the application, register the information provided in the store console |
| iOS share is rejected, but the Bundle ID is correct | If Debug and Release use different Bundle IDs, register both. A mismatch between the development certificate and the distribution certificate is also rejected |
| How to get the HarmonyOS appIdentifier | Print appIdentifier with the SDK's HarmonyCallerIdentity.capture() (the identifier field on the form). The value is the unique application identifier for the current signature. Debug and release signatures differ and must be registered separately |
After the steps above, integrate the share capability by following the Development Guide.
PC Development Guide
Supported versions: WorkBuddy 5.8.0 and later.
Capability Overview
A third-party application builds a share message, signs a packet with the application private key, and hands it to WorkBuddy through the PC HTTPS interstitial page or, later, the mobile SDK. After WorkBuddy validates the request, it prefills the content into the task input. The user can review, edit, and send. A successful launch or a successful prefill does not mean the user has submitted the task.
The current share scene value is always newTask. If the new-task input in WorkBuddy already has content, the shared content overwrites that input. Otherwise a new task is created and the content is filled into the task input. newTask is the name of a protocol scene. It does not mean every share is forced to create a brand-new task.
The message payload uses TaskPayload. Its content blocks can carry text, images, audio, file resources, and resource links. Support for local resources and embedded data differs by platform. See below.
Quick Start: Share a Text Message
The example below uses Node.js built-in modules. It signs on the server and produces the PC HTTPS interstitial link. You first need a real appId, kid, and the matching private key from the Open Platform. Save the private key as private-key.pem on the server, keeping the PEM header, footer, and line breaks. Do not commit this file to a repository.
Save the following code as sign.cjs:
const fs = require("node:fs");
const crypto = require("node:crypto");
const b64 = (value) => Buffer.from(value, "utf8").toString("base64");
const appId = process.env.APP_ID;
const kid = process.env.KEY_ID;
if (!appId || !kid) throw new Error("缺少 APP_ID 或 KEY_ID");
const messageObject = {
title: "分析仓库",
description: "请总结仓库结构",
payload: {
action: "start",
promptContentBlocks: [{ type: "text", text: "分析这个仓库" }],
},
};
const messageJson = JSON.stringify(messageObject);
if (Buffer.byteLength(messageJson, "utf8") > 16384) {
throw new Error("原始消息 JSON 超过 16 KiB");
}
const packet = {
appId,
kid,
message: b64(messageJson),
nonce: crypto.randomBytes(16).toString("hex"),
scene: "newTask",
timestamp: String(Math.floor(Date.now() / 1000)),
};
const signingText = [
`appId=${b64(packet.appId)}`,
`kid=${b64(packet.kid)}`,
`message=${packet.message}`,
`nonce=${b64(packet.nonce)}`,
`scene=${b64(packet.scene)}`,
`timestamp=${b64(packet.timestamp)}`,
].join("&");
packet.sig = crypto
.sign("sha256", Buffer.from(signingText, "utf8"), {
key: fs.readFileSync("./private-key.pem", "utf8"),
padding: crypto.constants.RSA_PKCS1_PADDING,
})
.toString("base64");
const query = new URLSearchParams(packet).toString();
console.log(`https://workbuddy.cn/app/open-deeplink?${query}`);Run it in the server directory where the private key is stored (replace the values with your application):
APP_ID='你的应用标识' KEY_ID='对应的密钥标识' node sign.cjs
Open the HTTPS interstitial link that is printed, and confirm that it launches WorkBuddy, prefills the message in the input, and then lets the user edit and send. Generate the signed packet when the user starts a share. Do not generate a link ahead of time and reuse it for a long time.
The Full PC Link
The PC side exposes an HTTPS interstitial page: https://workbuddy.cn/app/open-deeplink. The third-party application opens the link, with its parameters, in the system browser. After the user confirms, WorkBuddy is launched. If the client is not installed, the page can guide the user to install it.
The link uses seven query parameters: appId, kid, message, nonce, scene, timestamp, and sig. Encode the transport parameters with URLSearchParams. Do not concatenate the Base64 characters +, /, and = by hand.
The link below is a complete example of every field and value. It was produced with a temporary RSA-2048 key and verified locally, but app_demo and kid_demo are not registered on the platform, and the example timestamp expires. It cannot be used for a real share.
HTTPS interstitial page:
https://workbuddy.cn/app/open-deeplink?appId=app_demo&kid=kid_demo&message=eyJ0aXRsZSI6IkRlbW8iLCJkZXNjcmlwdGlvbiI6IkRlbW8iLCJwYXlsb2FkIjp7ImFjdGlvbiI6InN0YXJ0IiwicHJvbXB0Q29udGVudEJsb2NrcyI6W3sidHlwZSI6InRleHQiLCJ0ZXh0IjoiSGVsbG8gV29ya0J1ZGR5In1dfX0%3D&nonce=9f2c8b1a6d4e7035c8a912f0b7d6e453&scene=newTask×tamp=1791515336&sig=s%2Bbo02%2BkPMj%2BbJV9iuzAxsIo3oEoPVYLl%2FkgPqQe4J0MTEEqa2kxmSssB%2Bg%2BzhsD1UZrNTlMPLQfUbApszCx05ujCKJ%2Fmn5u3QdoiWsIwl7dejptqHLI9iLIndlVroeliQ7r1mKtZNjLElWH4GNCeQbA2taPZanBcrcTQ5LXPXRRouxmryDPq%2FgbFKH9%2FU5vAoZUFEnKI1NqMs1W2QkEvLhj6kDOz2NmffZK64mHrpMlip6v3hD3ImPECWen1xmJJhetTV4Iy8bsinsio3PG7ccNf9dqYtpevWPlQlQhl09GVvhfNrKjQREkJG5Y6SkA3pIoB8vbNdLSH09D1UgV2Q%3D%3D
URL-decode message above, then decode it as standard Base64. The UTF-8 JSON is:
{"title":"Demo","description":"Demo","payload":{"action":"start","promptContentBlocks":[{"type":"text","text":"Hello WorkBuddy"}]}}
%3D, %2B, and %2F are the URL encodings of the Base64 characters =, +, and /. The values used for signing are the field values before URL encoding. The values used in the link are the transport values after signing is complete.
Parameter Types and Message Structure
Transport Signature Packet
The table describes the transport values in the URL query parameters or the signature packet. message is a string in transit. It becomes a WorkBuddyMessage object only after decoding. The actual parameters of the mobile SDK follow its official API documentation.
| Parameter | Transport type | Format and meaning |
|---|---|---|
appId | string | Application identifier assigned by the Open Platform |
kid | string | Key identifier paired with the private key used for this signature |
message | string | Standard Base64 of the UTF-8 JSON. The raw JSON is at most 16,384 bytes |
nonce | string | 32 lowercase hexadecimal characters from 16 cryptographically random bytes. Only 0–9 and a–f |
scene | string | Currently fixed as newTask |
timestamp | string | Decimal string of a Unix timestamp in seconds, not milliseconds |
sig | string | Standard Base64 of the RS256 signature bytes. It is not part of the signing string |
The first six fields are signed. Together with sig there are seven fields. Do not send the public key used for verification.
WorkBuddyMessage
| Field | Type | Description |
|---|---|---|
title | string | Share title, at most 50 characters |
description | string | Content description, at most 200 characters |
payload | TaskPayload object | The task payload currently available |
Serialize the whole message object first, then count the bytes of the raw UTF-8 JSON. The 16 KiB limit applies to the raw JSON, not to the URL length and not to the length of the Base64 string. If you embed media in data, those characters count toward the JSON byte size as well.
TaskPayload
| Field | Type | Description |
|---|---|---|
action | string | Currently start is supported |
promptContentBlocks | ContentBlock[] | An ordered array of content blocks. Supported types may be mixed |
connectorIds | string[] | When connectors must be specified, the list of connector identifiers in the message payload |
The specified connectors should already be published, and they should belong to the same organization as the share application. Whether the user has authorized still affects whether the resource can be read.
ContentBlock Types
type | Content | Known fields and types | Description |
|---|---|---|---|
text | Text | text: string | Prefilled into the task input as-is |
image | Image | uri: string (required), mimeType?: string, name?: string | Downloaded over http(s), or copied from file:// into the workspace, then prefilled as an attachment. A failed remote download falls back to a resource link |
audio | Audio | uri: string (required), mimeType?: string, name?: string | Same as image |
resource | File resource | resource: object (required). Nested fields: resource.uri: string (required), resource.mimeType?: string, resource.text?: string | Resource information is nested in the resource object, not flat fields |
resource_link | Resource link | uri: string (required), name: string (required), mimeType?: string | Fields sit on the block itself. Shown as a link capsule. The leading icon comes from the application information returned by signature verification. _meta is discarded |
A ? in the table only means the field is optional. It is not a promise about field combinations or which fields are required. Any field not listed in the table is discarded, including embedded Base64 data and blob on image, audio, and resource, and _meta on resource_link. promptContentBlocks allows at most 50 blocks, and text content totals at most 8,000 characters. Whether WorkBuddy can read a resource path or link depends on what the PC client can access. A local file:// path that the third-party application can read is not necessarily readable by WorkBuddy.
Signature Generation: Detailed Steps
The signature algorithm is RS256: RSA PKCS#1 v1.5 padding and a SHA-256 digest. Sign with the RSA-2048 private key (PKCS#8 PEM) paired with kid. Keep and use the private key on the developer's server.
- Build the message object. Fill in
title,description, andTaskPayload. For example, the text message in Quick Start. - Serialize the JSON. JSON-serialize the whole message object and take the exact UTF-8 byte sequence. The raw JSON must not exceed 16,384 bytes. Do not serialize or modify the message again between signing and sending, or the bytes may change.
- Produce
message. Apply one standard Base64 encoding to the UTF-8 bytes from step 2. Keep+,/, and any required=padding. Use that value as-is when signing. Do not Base64-encodemessagea second time. - Prepare the other fields. Read
appIdandkid. Use a cryptographically secure random generator to produce 16 bytes, and convert them to a 32-character lowercase hexadecimalnonce. Produce the Unix-seconds stringtimestampfor this request. - Encode the plain field values separately. Apply standard Base64 to the UTF-8 bytes of each of
appId,kid,nonce, andtimestamp. Encode only the values. Do not encode=,&, or the parameter names. - Build the signing string. Join the fields in ASCII order of the key names,
appId → kid → message → nonce → timestamp. Parameter names are case-sensitive. Put a single&between items, and do not add a trailing space or newline:appId=Base64(appId)&kid=Base64(kid)&message=message&nonce=Base64(nonce)×tamp=Base64(timestamp) - Produce
sig. RS256-sign the UTF-8 bytes of the signing string from step 6, then apply standard Base64 to the signature bytes.sigis not included in the signing string it belongs to. - Build the transport link. Pass the six raw transport field values and
sigtoURLSearchParamsas seven query parameters. The URL carries the raw values such asappIdandkid, not theBase64(appId)andBase64(kid)used inside the signing string. - Check validity and retries. Require
-30 ≤ platform current time − timestamp ≤ 300, in seconds. A retry of the same share keeps the original packet. After a new share, or after the packet expires, generatenonce,timestamp, andsigagain. The sameappId + noncemay pass in-app verification at most 3 times.
When a signature fails, first compare the exact signing string both sides used: field order, case, Base64 padding, whether message was encoded twice, and whether a newline was mixed in. Then check that kid matches the private key. Do not put the private key, or a complete real share link, into a support ticket.
Sharing Resources and Connectors
Before sharing an image, audio, a file, or a link, confirm that the target platform supports that content form, and that WorkBuddy can read the referenced resource. Remote resource links should stay valid. A local file URI works only when the target platform can access it. On PC, do not rely on embedding an image, audio, or file directly in the message through data.
When a connector is required, put the connectors published under the application's organization in TaskPayload.connectorIds. If the user has not authorized, the resource cannot be accessed, or the content does not pass review, the share may not be prefilled. Let the user adjust the content and share again.
Error Handling and Launch Checklist
| Symptom | Check first | What to do |
|---|---|---|
| The client cannot be launched | Whether WorkBuddy is installed and is 5.8.0 or later, and whether the HTTPS interstitial link and its parameters are correct | Check that the interstitial page opens, and confirm the client is installed and updated |
| The application is unavailable | Whether the application has been reviewed and enabled | Check the application status on the Open Platform |
| The endpoint is unavailable or the identity does not match | PC registration, package name, Bundle ID, and signature information | Complete the endpoint registration, and compare the test build with the release build |
| Signature verification fails | Whether kid matches the private key, field order, Base64 versus URL encoding, and whether timestamp is used | Rebuild the signing string step by step following Signature Generation: Detailed Steps |
| The request is expired or repeated | Server clock, seconds versus milliseconds, and whether nonce was regenerated for a new share | Sync the clock, and sign again according to the retry rules |
| A resource or connector is unavailable | Resource URL lifetime, whether the target platform can access it, the connector's organization, and user authorization | Fix resource access, then share again |
| Content was not prefilled | Raw JSON byte size, content block type, whether the resource is readable, and the content review result | Start with a minimal text-only message to rule out a resource problem |
Before launch, verify at least: a plain-text share through the PC HTTPS interstitial page, the client not installed, a wrong private key, an expired request, a repeated request, an identity mismatch, and an unreachable resource.
iOS Integration Guide and Developer Guide
Integration Guide
This article describes how to integrate the WorkBuddy Open SDK into an iOS app and complete registration. For specific sharing methods, see the Developer Guide.
1. Environment Requirements
| Item | Requirement |
|---|---|
| System version | iOS 15.0 and above |
|Architecture|Physical device: arm64; simulator: arm64 / x86_64|
|Development tools|The distribution package is built and verified with Xcode 26.3 / Swift 6.2.4; earlier compilers have not been verified|
|Integration method|Swift Package Manager or CocoaPods; only one of them can be used for the same target|
|WorkBuddy|A WorkBuddy version that supports the OpenSDK sharing protocol (with the workbuddy-opensdk scheme registered) must be installed on the device|
2. Register Your App on the Open Platform
Before integration, complete the following registration on the WorkBuddy Open Platform:
-
Create an app and obtain an
appId. It must start withapp_, be 5–64 characters in total length, and contain only ASCII letters, digits, and underscores. -
Obtain a
kid, i.e. the key identifier, 1–128 visible ASCII characters. Even if signatures are not used,registerstill requires akid. If signatures are used, the key used for backend signing must correspond to thiskid; see OpenSDK Signature Developer Guide for details. -
Register iOS terminal information: the official Bundle ID, i.e.
Bundle.main.bundleIdentifier. If Debug and Release use different Bundle IDs, register both.
When WorkBuddy receives a share, it compares the Bundle ID automatically attached by the SDK with the registered value and rejects the request if they do not match. The SDK does not collect or need the Team ID.
To confirm the actual value, print
try IOSCallerIdentity.capture().bundleIdin a debug build; the result is the Bundle ID collected by the SDK at registration time.
3. Obtain the SDK
Obtain the iOS distribution package WorkBuddyOpenSDK-0.1.0.zip from SDK Version Notes and Resource Downloads. Remote SPM / CocoaPods addresses have not been published yet. After extracting, you get the WorkBuddyOpenSDK/ directory with the following main contents:
| File | Description |
|---|---|
Binary/WorkBuddyOpen.xcframework | Precompiled static library (.a) and Swift module interfaces |
Package.swift | SPM manifest, exporting the product WorkBuddyOpen |
WorkBuddyOpenSDK.podspec | CocoaPods spec, with the Pod name WorkBuddyOpenSDK |
Sources/ | A resource target containing only the privacy manifest PrivacyInfo.xcprivacy, automatically packaged by the SPM or Pods resource bundle |
release-info.json, VERSION | Version and checksum values |
DISTRIBUTION-NOTICE.txt | Distribution notes (no official license yet) |
Do not link the bare xcframework directly into your app. Integrate through SPM or CocoaPods so that the privacy manifest and Swift module search paths are configured automatically.
4. Integrate the SDK
Method 1: Swift Package Manager
In Xcode, choose File → Add Package Dependencies… → Add Local…, select the extracted WorkBuddyOpenSDK directory, and add the product WorkBuddyOpen to your app target.
If you manage dependencies with Package.swift:
dependencies: [
.package(path: "../WorkBuddyOpenSDK")
],
targets: [
.target(name: "YourApp", dependencies: [
.product(name: "WorkBuddyOpen", package: "WorkBuddyOpenSDK")
])
]
Method 2: CocoaPods
Add the following to the corresponding target in your Podfile:
pod 'WorkBuddyOpenSDK', :path => '../WorkBuddyOpenSDK'
Run pod install, then open the generated .xcworkspace.
The import statement is the same for both methods:
import WorkBuddyOpen5. Project Configuration
5.1 Configure the query allowlist (required)
Append the following two items to LSApplicationQueriesSchemes in Info.plist; keep any existing items:
<key>LSApplicationQueriesSchemes</key>
<array>
<string>workbuddy</string>
<string>workbuddy-opensdk</string>
</array>
| scheme | Purpose | Behavior when missing |
|---|---|---|
workbuddy | checkAppInstallation() installation detection | Returns UNKNOWN |
workbuddy-opensdk | Share capability check before share | Sharing returns FAILED / UNAVAILABLE |
Starting with iOS 15, the system only recognizes the first 50 entries of
LSApplicationQueriesSchemes. If your list is long, make sure these two items are within the first 50.
5.2 Configuration Not Required
Unlike other mobile sharing SDKs, none of the following configurations are required:
-
URL Types / URL Scheme: WorkBuddy does not switch back to your app.
-
Universal Links, Associated Domains: not used by the current protocol.
-
Callbacks such as
application(_:open:options:)andscene(_:openURLContexts:): the SDK has no callbacks to handle. -
Photo library, file, and other permissions: the SDK does not proactively request any permission; it only reads the data you pass in or files you already have access to.
6. Registration
Call register once when the app starts (for example, in application(_:didFinishLaunchingWithOptions:)), and you must explicitly pass NativeShareTransport():
import UIKit
import WorkBuddyOpen
@main
@MainActor
final class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
do {
try WorkBuddyOpen.register(
appId: "app_YOUR_REGISTERED_ID",
kid: "key_YOUR_REGISTERED_KEY",
transport: NativeShareTransport()
)
} catch ShareInitializationError.alreadyRegistered {
// 本进程已注册过,沿用首次配置
} catch {
// invalidAppId / invalidKid / unavailableBundleId / invalidIdentity:检查参数和工程配置
}
return true
}
}Registration rules:
-
All
WorkBuddyOpenmethods are on@MainActor; call them on the main thread. -
The SDK automatically reads the Bundle ID from
Bundle.mainand stores it; you do not need to fill it in manually. Thebundleparameter can take anotherBundle, but normally the default value is sufficient. -
Registration can succeed only once per process. Any subsequent
registercall (even with identical parameters) throwsShareInitializationError.alreadyRegistered, and the first configuration remains unchanged. The SDK provides no unregister or reset; to changeappId/kidyou must restart the process. -
A failed first registration leaves no state; you can retry after fixing the parameters.
-
Calling
sharebefore registration returnsFAILED / NOT_REGISTERED. -
If
transportis not passed, a placeholder implementation is used and every share returnsFAILED / NOT_IMPLEMENTED.
For the values of the registration exception ShareInitializationError, see Registration Exceptions.
7. Detect Whether WorkBuddy Is Installed
No registration is required; you can call it synchronously at any time:
switch WorkBuddyOpen.checkAppInstallation() {
case .detected: break // 检测到 WorkBuddy;能否分享仍由 share 判断
case .notDetected: break // 未检测到;不能据此断定一定未安装
case .unknown: break // Info.plist 未声明 workbuddy,或当前环境无法查询
@unknown default: break
}-
Every call performs a real-time query, does not cache the result, and does not launch WorkBuddy.
-
The system can only tell the SDK that some app can handle
workbuddy://; it cannot confirm that it is WorkBuddy, nor that its version supports sharing. -
The
rawValues areDETECTED,NOT_DETECTED, andUNKNOWN, consistent with Android / HarmonyOS.
8. Guide Users to Download WorkBuddy
Call this when the user actively taps "Download WorkBuddy":
let accepted = await WorkBuddyOpen.openAppStore()
if !accepted {
// 系统拒绝打开,由你决定提示文案
}-
It always opens
https://apps.apple.com/app/id6761374913; no registration and no additional query allowlist are required. -
Returning
trueonly means the system accepted opening the link; it does not mean the page loaded successfully, that the app is available in the current region, or that the user has downloaded and installed it. -
The SDK does not automatically jump to the store, does not retry automatically, and does not automatically resume sharing after installation.
9. Verify the Integration
-
Install an OpenSDK-capable WorkBuddy on a physical device and sign in.
-
Run your app:
checkAppInstallation()should return.detected. -
Perform one text share;
shareshould returnHANDED_OFFand launch WorkBuddy. -
In WorkBuddy, confirm that the text appears in the input box. If it does not, follow the troubleshooting checklist to check the registration information and sign-in status.
10. Privacy and Compliance
-
The SDK does not collect device identifiers, does not report data, and does not log shared content.
-
The privacy manifest
PrivacyInfo.xcprivacydeclares only the file timestamp API (reasonC617.1), used to clean up expired temporary files created by the SDK itself. -
The only identity information the SDK collects is your own app's Bundle ID, which is passed to WorkBuddy with the share request to verify the Open Platform registration.
-
The personal information processing rules and the official license agreement are pending release.
Developer Guide
Before reading this article, complete the integration, Info.plist configuration, and registration in the Integration Guide.
Basic Calls
WorkBuddyOpen.share(_:) is an async throws method on @MainActor that returns a ShareResult:
import WorkBuddyOpen
@MainActor
func shareText() async {
do {
let result = try await WorkBuddyOpen.share(TextShareRequest(text: "分享内容"))
handle(result)
} catch is CancellationError {
// 调用方取消了所在 Task
} catch {
// 非预期错误
}
}For all request types, the constructor parameter order is: content first, then the optional signature and metadata; for file requests, fileName and mimeType come next; suggestions comes last. All parameters have default values and can be omitted as needed.
Share Text
let request = TextShareRequest(
text: "季度复盘要点:\n1. 收入增长 12%\n2. 新增客户 30 家",
metadata: ShareMetadata(title: "季度复盘"),
suggestions: ["总结主要观点", "整理待办事项"]
)
let result = try await WorkBuddyOpen.share(request)| Parameter | Type | Required | Description |
|---|---|---|---|
text | String | Yes | Cannot be empty or contain only whitespace; up to 64 KiB (UTF-8). Spaces, newlines, and Unicode are preserved as-is |
Share a Link
let request = LinkShareRequest(
url: "https://www.example.com/article/123",
metadata: ShareMetadata(title: "文章标题", description: "文章摘要")
)
let result = try await WorkBuddyOpen.share(request)| Parameter | Type | Required | Description |
|---|---|---|---|
url | String | Yes | An absolute http / https URL with a host name, up to 16 KiB. The SDK does not rewrite the URL. For format requirements, see Mobile Sharing Overview |
WorkBuddy displays the link as a card whose title uses metadata.title; if it is not set, the URL is displayed.
Share an Image
let imageData: Data = try Data(contentsOf: imageFileURL) // 原始 PNG / JPEG 字节
let request = ImageShareRequest(
image: .fromData(imageData),
metadata: ShareMetadata(thumbnail: thumbnailData.map { .fromData($0) })
)
let result = try await WorkBuddyOpen.share(request)| Parameter | Type | Required | Description |
|---|---|---|---|
image | ShareMediaSource | Yes | PNG / JPEG only, up to 20 MiB; each side ≤ 16,384 pixels, total pixels ≤ 40,000,000 |
-
Use the original image data. Do not convert it to
UIImagefirst and re-encode it withpngData()/jpegData(). Re-encoding changes the byte content and causes a digest mismatch when signatures are used. -
The SDK identifies the format from the file header and does not transcode or compress.
-
Internally, the SDK names the image
image.pngorimage.jpg, with the MIME typeimage/pngorimage/jpeg.
Share a File
let request = FileShareRequest(
file: .fromFileURL(pdfURL),
fileName: "2026Q3-复盘.pdf",
mimeType: "application/pdf"
)
let result = try await WorkBuddyOpen.share(request)| Parameter | Type | Required | Description |
|---|---|---|---|
file | ShareMediaSource | Yes | Up to 100 MiB; cannot be an empty file |
fileName | String? | No | Display file name, up to 255 bytes. Passing a name with an extension is strongly recommended; if omitted, it defaults to file and may be rejected by WorkBuddy's file type filter |
mimeType | String? | No | type/subtype format without parameters, up to 127 bytes; defaults to application/octet-stream if omitted |
Media Source ShareMediaSource
| Factory method | Use case | Description |
|---|---|---|
ShareMediaSource.fromData(_ data: Data) | Data in memory | Copies the data at construction time; later changes to the original Data do not affect the request |
ShareMediaSource.fromFileURL(_ url: URL) | A local file, or a file obtained through a file picker | Only stores the URL at construction time; the file is read only after share passes the capability check |
-
Constructing a
ShareMediaSourcedoes not read files, download network resources, or request any permission. -
For security-scoped URLs returned by
UIDocumentPickerViewControllerand similar APIs, the SDK attempts to callstartAccessingSecurityScopedResource()and releases access after copying; you may also obtain access in advance yourself. -
If the file is unreadable or access is not granted,
FAILED / RESOURCE_UNAVAILABLEis returned. -
The SDK reads in 64 KiB chunks and computes SHA-256, stopping the read immediately once the limit is exceeded. Reading runs in a background task and does not block the main thread.
-
Do not modify or delete the source file before
sharereturns.
Title, Description, and Thumbnail ShareMetadata
ShareMetadata(
title: "标题", // 可选,最多 1 KiB
description: "描述", // 可选,最多 4 KiB
thumbnail: .fromData(png) // 可选,PNG / JPEG,最多 256 KiB
)-
All four request types can carry
metadata; when omitted, it is empty. -
The thumbnail and the original image are independent: the thumbnail cannot replace the original image, nor is it generated automatically from it.
-
The current version of WorkBuddy only validates the thumbnail and does not display it.
Suggestions suggestions
TextShareRequest(text: "会议纪要……", suggestions: ["总结主要观点", "整理待办事项", "提炼关键结论"])-
The type is
[String], defaulting to an empty array. The SDK keeps only the first 3 entries verbatim in order; duplicates and whitespace-only entries are also kept and occupy a slot. -
The SDK does not trim, truncate, or rewrite suggestion content. WorkBuddy displays at most the first 14 characters of each entry; when the user taps it, the content is appended to the input box.
-
When signatures are used, the backend must compute digests for these 3 verbatim entries in order; see OpenSDK Signature Developer Guide
Sharing with a Signature
If the backend has generated a signature package, pass the 5 fields verbatim:
// 从你自己的后台获取本次分享的签名包
let signature = SignaturePayload(
kid: payload.kid, // 必须与 register 时的 kid 完全一致
message: payload.message,
nonce: payload.nonce,
timestamp: payload.timestamp, // 字符串,不要转成数字
sig: payload.sig
)
let result = try await WorkBuddyOpen.share(
TextShareRequest(text: text, signature: signature, suggestions: suggestions)
)-
The signature package is bound to the content of this request. Finalize the text, title, description, media, and suggestions before requesting a backend signature, and do not modify them afterward.
-
If
signature.kiddoes not match the registeredkid, the SDK immediately returnsFAILED / INVALID_SIGNATURE. Apart from that, the SDK does not validate the signature content; WorkBuddy is responsible for verification. -
The signature package has a short validity period (the server uses
timestamp, at most 300 seconds); obtain it right before sharing and do not cache it. -
Once a signature is provided, WorkBuddy rejects the share if verification fails; it does not fall back to unsigned sharing.
Handling Share Results
func handle(_ result: ShareResult) {
switch result.status {
case .handedOff:
// 已拉起 WorkBuddy 并交出内容。不代表已到达输入框,也不代表用户已发送
break
case .failed:
switch result.errorCode {
case .notRegistered: break // 未调用 register
case .notImplemented: break // register 时没有传 NativeShareTransport()
case .unavailable: break // 检查 LSApplicationQueriesSchemes 是否声明 workbuddy-opensdk
case .unsupportedCapability: break // WorkBuddy 未安装或版本不支持,可引导 openAppStore()
case .payloadTooLarge: break // 内容超过大小限制
default: break
}
case .cancelled:
break // 预留状态,当前内置 transport 不会返回
@unknown default:
break
}
}-
result.requestIdis a UUID generated by the SDK for this call, used only to correlate logs within your app; it is not a server-side ID. -
For the full list of error codes, see Results and Error Codes.
Notes
-
Call in the foreground: call
sharewhen the app is in the foreground and triggered by a user action, so the system can launch WorkBuddy. -
Large files go through the clipboard: images or files with an original size ≥ 460,800 bytes (450 KiB) are handed to WorkBuddy as files via the local clipboard, valid for 10 minutes and not synced across devices. If your app or another app overwrites the clipboard before WorkBuddy reads it, this share is rejected by WorkBuddy, and the
HANDED_OFFalready returned by the SDK will not change. -
Only one large-file share at a time: within the same process, a later share reclaims the previous unread clipboard file.
-
Cancellation: when the
Taskcallingshareis cancelled, the SDK checks the cancellation state between reads and throwsCancellationError. -
Repeated calls: every
sharegenerates a newrequestId. With signatures, WorkBuddy deduplicates byappId + nonce; sharing the same signature package again is ignored as a duplicate request. Every new share requires a new signature package signed by the backend.
Android Integration Guide and Developer Guide
Integration Guide
This article describes how to integrate the WorkBuddy Open SDK into an Android app and complete registration. For specific sharing methods, see the Developer Guide.
1. Environment Requirements
| Item | Requirement |
|---|---|
| Minimum system version | Android 6.0 (API 23) |
| Build environment | JDK 17; the SDK is built with compileSdk 35 |
| Project requirements | AndroidX enabled; call share with Kotlin coroutines (a suspend function) |
| Transitive dependencies | Kotlin stdlib, androidx.core:core:1.15.0, org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2 (resolved automatically when integrating via Maven) |
| WorkBuddy | A WorkBuddy installed on the device with package name com.tencent.workbuddy.app, versionName ≥ 1.0.0, and OpenSDK protocol v1 declared |
2. Register Your App on the Open Platform
Before integration, complete the following registration on the WorkBuddy Open Platform:
- Create an app and obtain an
appId. It must start withapp_, be 5–64 characters in total length, and contain only ASCII letters, digits, and underscores. - Obtain a
kid, i.e. the key identifier, 1–128 visible ASCII characters. Even if signatures are not used,registerstill requires akid. - Register Android terminal information:
- Package name (
applicationId); - Signing certificate SHA-256 fingerprint: 64-character uppercase hexadecimal, without colons.
- Package name (
When WorkBuddy receives a share, it checks whether the package name attached by the SDK matches the registered value, and whether the registered fingerprint is in the set of signing certificate fingerprints collected by the SDK; it rejects the request if either does not match.
Obtaining the signing certificate SHA-256 fingerprint
Method 1: use keytool to view the signing certificate, take the SHA256: line, remove the colons and convert to uppercase:
keytool -list -v -keystore your-release.jks -alias your-alias
Method 2: print the value the SDK will collect directly in a debug build (the same collection logic as at registration):
val identity = com.tencent.workbuddy.opensdk.AndroidIdentity.capture(context)
Log.d("WorkBuddy", "${identity.packageName} ${identity.certificateFingerprints}")Notes:
- Debug and Release usually use different signing certificates; register the fingerprint of whichever build you are testing.
- If you use a store re-signing scheme such as Google Play App Signing, the app actually installed on user devices is signed by the store; register the app signing certificate fingerprint provided by the store console.
- On Android 9 (API 28) and above, the SDK reads all current signers; historical certificates before rotation are not included.
3. Obtain the SDK
Obtain the Android distribution package WorkBuddyOpenSDK-Android-0.1.0.zip from SDK Version Notes and Resource Downloads. It has not been published to a public Maven repository yet. After extracting, it contains a local Maven repository directory maven/ with the AAR, POM, Gradle module metadata, and sources package. The Maven coordinates are:
com.tencent.workbuddy:open-sdk:0.1.0
4. Integrate the SDK
4.1 Add the repository
Add the extracted maven/ directory in settings.gradle.kts, while keeping the Google / Maven Central repositories to resolve the SDK's transitive dependencies:
dependencyResolutionManagement {
repositories {
maven {
url = uri("/path/to/distribution/maven")
content { includeModule("com.tencent.workbuddy", "open-sdk") }
}
google()
mavenCentral()
}
}4.2 Add the dependency
In the app module's build.gradle.kts:
dependencies {
implementation("com.tencent.workbuddy:open-sdk:0.1.0")
}
You can also copy only the AAR and add it with
implementation(files("libs/open-sdk-0.1.0.aar")). However, this does not resolve the POM, so you must supply Kotlin stdlib,androidx.core:core:1.15.0, andkotlinx-coroutines-android:1.10.2of the same version yourself. Integrating via the Maven directory is recommended. Do not include both the AAR and the SDK source module, or duplicate classes will occur.
5. Project Configuration
5.1 Manifest content merged automatically
The AAR ships with the following declarations, which are merged into your app automatically at build time; you do not need to add them manually:
<queries>
<package android:name="com.tencent.workbuddy.app" />
</queries>
<application>
<provider
android:name="com.tencent.workbuddy.opensdk.WorkBuddyShareFileProvider"
android:authorities="${applicationId}.workbuddy.opensdk.files"
android:exported="false"
android:grantUriPermissions="true" />
</application>
<queries>lets Android 11 and above see the WorkBuddy package; both installation detection and the share capability check depend on it. Do not remove it withtools:node="remove". After removal,checkAppInstallationmay returnNOT_DETECTEDand sharing returnsUNAVAILABLE.- The FileProvider is used only to grant WorkBuddy temporary read-only access to image and file copies generated by the SDK itself. Its authority carries your
applicationIdprefix and does not conflict with other FileProviders. - The SDK does not need
QUERY_ALL_PACKAGES, storage permissions, or network permissions.
5.2 Code obfuscation
The AAR ships with consumer obfuscation rules, which take effect automatically when R8 / ProGuard is enabled; no extra configuration is needed. The rules are listed below for reference only:
-keepattributes RuntimeVisibleAnnotations
-keep @interface com.tencent.workbuddy.opensdk.MinVersion
-keep interface com.tencent.workbuddy.opensdk.ShareApi { *; }
5.3 Configuration Not Required
- Callback Activity (e.g.
WXEntryActivity): WorkBuddy does not call back into your app; no callback component needs to be declared. - Broadcast receiver or Intent Filter: not required.
6. Registration
It is recommended to call register once in Application.onCreate, and you must explicitly pass NativeShareTransport(context):
import android.app.Application
import com.tencent.workbuddy.opensdk.NativeShareTransport
import com.tencent.workbuddy.opensdk.ShareInitializationErrorCode
import com.tencent.workbuddy.opensdk.ShareInitializationException
import com.tencent.workbuddy.opensdk.WorkBuddyOpen
class App : Application() {
override fun onCreate() {
super.onCreate()
try {
WorkBuddyOpen.register(
this,
appId = "app_YOUR_REGISTERED_ID",
kid = "key_YOUR_REGISTERED_KEY",
transport = NativeShareTransport(this),
)
} catch (e: ShareInitializationException) {
// e.code == ShareInitializationErrorCode.ALREADY_REGISTERED:本进程已注册,沿用首次配置
} catch (e: IllegalArgumentException) {
// appId / kid / 包名 / 证书指纹格式无效
} catch (e: IllegalStateException) {
// 无法读取本应用签名证书
}
}
}Registration rules:
- The SDK automatically reads the app's package name and the current signing certificate SHA-256 fingerprint; you do not need to fill them in manually. The SDK does not hold the passed
Context; it only usesapplicationContext. - Registration can succeed only once per process. Any subsequent
registercall throwsShareInitializationException(code == ALREADY_REGISTERED), even with identical parameters, and the first configuration remains unchanged. The SDK provides no unregister or reset. In a multi-process app, every process that needs to share must register on its own. ShareInitializationExceptioninherits fromIllegalStateException, so catch it first.- A failed first registration leaves no state; you can retry after fixing the problem.
- Calling
sharebefore registration returnsFAILED / NOT_REGISTERED. - If
transportis not passed, a placeholder implementation is used and every share returnsFAILED / NOT_IMPLEMENTED.
When calling from Java, all parameters must be passed:
WorkBuddyOpen.register(context, "app_YOUR_REGISTERED_ID", "key_YOUR_REGISTERED_KEY", new NativeShareTransport(context));
7. Detect Whether WorkBuddy Is Installed
No registration is required; you can call it synchronously at any time, and Java can call it directly too:
when (WorkBuddyOpen.checkAppInstallation(context)) {
AppInstallationStatus.DETECTED -> { /* 检测到 WorkBuddy;能否分享仍由 share 判断 */ }
AppInstallationStatus.NOT_DETECTED -> { /* 未检测到;可能未安装或系统可见性受限 */ }
AppInstallationStatus.UNKNOWN -> { /* 平台查询失败,可稍后重试 */ }
}- Only queries
com.tencent.workbuddy.appunder the current user; every call is a real-time query with no cached result. - It does not compare versions or check protocol support. An installed but disabled WorkBuddy also returns
DETECTED. NOT_DETECTEDcannot be used as evidence that the app is definitely uninstalled.
8. Guide Users to Download WorkBuddy
On Android, only the official website URL is provided; you decide whether to display, copy, or open it:
val url = WorkBuddyOpen.getOfficialWebsiteUrl() // "https://www.workbuddy.cn/"
startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(url)))This method requires neither registration nor a Context; it does not access the network, open a browser, or download an APK.
9. Verify the Integration
- Install an OpenSDK-capable WorkBuddy on a physical device and sign in.
- Run your app:
checkAppInstallationshould returnDETECTED. - Perform one text share;
shareshould returnHANDED_OFFand launch WorkBuddy. - In WorkBuddy, confirm that the text appears in the input box. If it does not, follow the troubleshooting checklist in the Open API section to check the package name, certificate fingerprint registration, and sign-in status.
10. Privacy and Compliance
- The SDK does not collect device identifiers, does not report data, and does not log shared content.
- The only identity information the SDK collects is your own app's package name and signing certificate fingerprint, which are passed to WorkBuddy with the share request to verify the Open Platform registration.
- The personal information processing rules and the official license agreement are pending release.
Developer Guide
Before reading this article, complete the integration and registration in the Integration Guide.
Basic Calls
WorkBuddyOpen.share(request) is a suspend function that returns a ShareResult. It can be called from any coroutine; internally the SDK switches file reading to Dispatchers.IO and launching WorkBuddy to the main thread:
import androidx.lifecycle.lifecycleScope
import com.tencent.workbuddy.opensdk.*
import kotlinx.coroutines.launch
lifecycleScope.launch {
val result = WorkBuddyOpen.share(TextShareRequest("分享内容"))
handle(result)
}For all request types, the constructor parameter order is: content first, then the optional signature and metadata; for file requests, fileName and mimeType come next; suggestions comes last. In Kotlin, named arguments are recommended.
Share Text
val request = TextShareRequest(
text = "季度复盘要点:\n1. 收入增长 12%\n2. 新增客户 30 家",
metadata = ShareMetadata(title = "季度复盘"),
suggestions = listOf("总结主要观点", "整理待办事项"),
)
val result = WorkBuddyOpen.share(request)| Parameter | Type | Required | Description |
|---|---|---|---|
text | String | Yes | Cannot be empty or contain only whitespace; up to 64 KiB (UTF-8); cannot contain unpaired UTF-16 surrogate characters |
Share a Link
val request = LinkShareRequest(
url = "https://www.example.com/article/123",
metadata = ShareMetadata(title = "文章标题", description = "文章摘要"),
)
val result = WorkBuddyOpen.share(request)| Parameter | Type | Required | Description |
|---|---|---|---|
url | String | Yes | An absolute http / https URL with a host name, up to 16 KiB. The SDK does not rewrite the URL. For format requirements, see Mobile Sharing Overview |
Share an Image
val bytes: ByteArray = contentResolver.openInputStream(imageUri)!!.use { it.readBytes() }
val request = ImageShareRequest(
image = ShareMediaSource.fromBytes(bytes),
metadata = ShareMetadata(thumbnail = thumbnailBytes?.let(ShareMediaSource::fromBytes)),
)
val result = WorkBuddyOpen.share(request)You can also pass a URI directly without reading it into memory first:
ImageShareRequest(image = ShareMediaSource.fromContentUri(imageUri))| Parameter | Type | Required | Description |
|---|---|---|---|
image | ShareMediaSource | Yes | PNG / JPEG only, up to 20 MiB; each side ≤ 16,384 pixels, total pixels ≤ 40,000,000 |
- Use the original image data. Do not decode it into a
Bitmapand then callcompress(). Re-encoding changes the byte content and causes a digest mismatch when signatures are used. - The SDK identifies the format from the file header and does not transcode or compress.
- Internally, the SDK names the image
image.pngorimage.jpg, with the MIME typeimage/pngorimage/jpeg.
Share a File
val request = FileShareRequest(
file = ShareMediaSource.fromContentUri(documentUri),
fileName = "2026Q3-复盘.pdf",
mimeType = "application/pdf",
)
val result = WorkBuddyOpen.share(request)| Parameter | Type | Required | Description |
|---|---|---|---|
file | ShareMediaSource | Yes | Up to 100 MiB; cannot be an empty file |
fileName | String? | No | Display file name, up to 255 bytes. Passing a name with an extension is strongly recommended; if omitted, it defaults to file and may be rejected by WorkBuddy's file type filter |
mimeType | String? | No | type/subtype format without parameters, up to 127 bytes; defaults to application/octet-stream if omitted |
Media Source ShareMediaSource
| Factory method | Use case | Description |
|---|---|---|
ShareMediaSource.fromBytes(ByteArray) | Data in memory | Copies the data at construction time. Reading the bytes property also returns a copy |
ShareMediaSource.fromFile(File) | A local file readable by the app, e.g. a file in a private directory | Only stores the path at construction time |
ShareMediaSource.fromContentUri(Uri) | A content:// URI, e.g. one returned by ACTION_OPEN_DOCUMENT or a photo picker | Must use the content scheme and include an authority |
- Construction does not read files, download network resources, or request URI permissions. The SDK starts reading only after the capability check passes.
- Your app must already hold read permission for the URI. The SDK does not call
takePersistableUriPermission. If the URI permission is valid only for the lifetime of a certain Activity, complete the share while it is still valid. - If the file does not exist, is unreadable, or permission is missing,
FAILED / RESOURCE_UNAVAILABLEis returned. - The SDK reads the source file, generates a copy in its own cache directory, and then grants WorkBuddy temporary read-only access through the SDK's built-in FileProvider (granted only to
com.tencent.workbuddy.app). The source file is not modified, and its path is not handed to WorkBuddy. - Do not modify or delete the source file before
sharereturns.
Title, Description, and Thumbnail ShareMetadata
ShareMetadata(
title = "标题", // 可选,最多 1 KiB
description = "描述", // 可选,最多 4 KiB
thumbnail = ShareMediaSource.fromBytes(png), // 可选,PNG / JPEG,最多 256 KiB
)- All four request types can carry
metadata; when omitted, it is empty. - The thumbnail and the original image are independent: the thumbnail cannot replace the original image, nor is it generated automatically from it.
- The current version of WorkBuddy only validates the thumbnail and does not display it.
Suggestions suggestions
TextShareRequest("会议纪要……", suggestions = listOf("总结主要观点", "整理待办事项", "提炼关键结论"))- The type is
List<String>, defaulting to an empty list. The SDK keeps only the first 3 entries verbatim in order; duplicates and whitespace-only entries are also kept and occupy a slot. Later changes to the passed list do not affect the request. - The SDK does not trim, truncate, or rewrite suggestion content. WorkBuddy displays at most the first 14 characters of each entry; when the user taps it, the content is appended to the input box.
- When signatures are used, the backend must compute digests for these 3 verbatim entries in order; see OpenSDK Signature Developer Guide.
Sharing with a Signature
// 从你自己的后台获取本次分享的签名包
val signature = SignaturePayload(
kid = payload.kid, // 必须与 register 时的 kid 完全一致
message = payload.message,
nonce = payload.nonce,
timestamp = payload.timestamp, // String,不要转成数字
sig = payload.sig,
)
val result = WorkBuddyOpen.share(TextShareRequest(text, signature = signature, suggestions = suggestions))- The signature package is bound to the content of this request. Finalize the text, title, description, media, and suggestions before requesting a backend signature, and do not modify them afterward.
- If
signature.kiddoes not match the registeredkid, the SDK immediately returnsFAILED / INVALID_SIGNATURE. Apart from that, the SDK does not validate the signature content; WorkBuddy is responsible for verification. - The signature package has a short validity period (the server uses
timestamp, at most 300 seconds); obtain it right before sharing and do not cache it. - Once a signature is provided, WorkBuddy rejects the share if verification fails; it does not fall back to unsigned sharing.
Handling Share Results
fun handle(result: ShareResult) {
when (result.status) {
ShareStatus.HANDED_OFF -> {
// 已拉起 WorkBuddy 并交出内容。不代表已到达输入框,也不代表用户已发送
}
ShareStatus.FAILED -> when (result.errorCode) {
ShareErrorCode.NOT_REGISTERED -> { /* 未调用 register */ }
ShareErrorCode.NOT_IMPLEMENTED -> { /* register 时没有传 NativeShareTransport */ }
ShareErrorCode.UNAVAILABLE -> { /* WorkBuddy 未安装、不可见或无法识别版本 */ }
ShareErrorCode.UNSUPPORTED_CAPABILITY -> { /* WorkBuddy 版本过低,引导用户升级 */ }
ShareErrorCode.PAYLOAD_TOO_LARGE -> { /* 内容超过大小限制 */ }
else -> { /* 见错误码文档 */ }
}
ShareStatus.CANCELLED -> { /* 预留状态,当前内置 transport 不会返回 */ }
}
}result.requestIdis a UUID generated by the SDK for this call, used only to correlate logs within your app; it is not a server-side ID.- For the full list of error codes, see Results and Error Codes.
Java Calls
share is a Kotlin suspend function and cannot be called directly from Java. It is recommended to wrap it in Kotlin and expose a callback or CompletableFuture to Java. register, checkAppInstallation, getOfficialWebsiteUrl, and the request class constructors can all be called directly from Java. Constructors have no default-parameter overloads, so all parameters must be passed explicitly:
TextShareRequest request = new TextShareRequest("分享内容", null, new ShareMetadata(null, null, null), Collections.emptyList());Notes
- Call in the foreground: the SDK launches WorkBuddy via
startActivity. Starting with Android 10, the system restricts background Activity launches, so call it when the app is in the foreground and triggered by a user action. - Capability check: before every share, the SDK checks whether
com.tencent.workbuddy.appdeclares OpenSDK protocol v1 and whetherversionNameis ≥ 1.0.0. - Copy reclamation: the SDK keeps media copies for at most 4 requests at a time, each for up to 10 minutes. When exceeded, it reclaims the earliest request and revokes its URI grant; if WorkBuddy has not finished reading, the read fails. Avoid sharing multiple large files in rapid succession.
- Cancellation: when the enclosing coroutine is cancelled, the SDK checks the cancellation state between reads and throws
CancellationException; it does not convert it into aCANCELLEDresult. - Repeated calls: every
sharegenerates a newrequestId. With signatures, WorkBuddy deduplicates byappId + nonce; sharing the same signature package again is ignored as a duplicate request. Every new share requires a new signature package signed by the backend.
HarmonyOS Integration Guide and Developer Guide
Integration Guide
This article describes how to integrate the WorkBuddy Open SDK into a HarmonyOS app and complete registration. For specific sharing methods, see the Developer Guide.
1. Environment Requirements
| Item | Requirement |
|---|---|
| System version | HarmonyOS 6.0.0 (API 20) and above, consistent with the SDK's compatibleSdkVersion |
| Development tools | DevEco Studio; dependencies resolved with OHPM |
| Application model | Stage model; registration, sharing, and download guidance all require common.UIAbilityContext |
| WorkBuddy | A WorkBuddy version installed on the device that registers the workbuddy-opensdk://share entry |
2. Register Your App on the Open Platform
Before integration, complete the following registration on the WorkBuddy Open Platform:
- Create an app and obtain an
appId. It must start withapp_, be 5–64 characters in total length, and contain only ASCII letters, digits, and underscores. Note that it is not the HarmonyOSappIdentifier. - Obtain a
kid, i.e. the key identifier, 1–128 visible ASCII characters. Even if signatures are not used,registerstill requires akid. - Register HarmonyOS terminal information:
- bundleName;
- appIdentifier: the unique app identifier in the signing information;
- Signing certificate SHA-256 fingerprint: 64-character uppercase hexadecimal, without colons.
For unsigned shares, WorkBuddy checks bundleName and appIdentifier; for signed shares, all three are checked.
Obtaining terminal information
The most reliable method is to print the values the SDK actually collects in a debug build:
import { HarmonyCallerIdentity } from "@workbuddy/open-sdk";
const identity = HarmonyCallerIdentity.capture();
console.info(
`${identity.bundleName} ${identity.appIdentifier} ${identity.certificateFingerprint}`,
);capture() reads your own app's signing information and requires no permissions. Debug signing and release signing usually produce different appIdentifier and certificate fingerprints; register the values corresponding to the signing you are testing.
3. Obtain the SDK
Obtain workbuddy-open-sdk-0.1.0.har from SDK Version Notes and Resource Downloads. It has not been published to the OHPM central repository yet. The package name is @workbuddy/open-sdk, and the contents are a pure ArkTS implementation compiled in Release mode.
4. Integrate the SDK
-
Copy the HAR into your project, for example
libs/workbuddy-open-sdk-0.1.0.har. -
Declare the dependency in the
oh-package.json5of the module that uses the SDK:{ "dependencies": { "@workbuddy/open-sdk": "file:../libs/workbuddy-open-sdk-0.1.0.har" } } -
Run
ohpm install --all. -
Import it in code:
import { WorkBuddyOpen, NativeShareTransport } from '@workbuddy/open-sdk';
5. Project Configuration
5.1 Configure querySchemes (required)
Append the following two items to src/main/module.json5 in the entry module; keep any existing items:
{
"module": {
"querySchemes": ["workbuddy", "workbuddy-opensdk"]
}
}
| scheme | Purpose | Behavior when missing |
|---|---|---|
workbuddy | checkAppInstallation() installation detection | Returns UNKNOWN |
workbuddy-opensdk | Share capability check before share | Sharing returns FAILED / UNAVAILABLE |
- This configuration can only be written in the host entry module; the HAR cannot declare it on behalf of the host.
querySchemesallows at most 50 entries, of which the SDK uses two.
5.2 Permissions
The SDK does not need to request any permission:
- Installation detection and the share capability check use
bundleManager.canOpenLinkand do not requireGET_BUNDLE_INFOorGET_BUNDLE_INFO_PRIVILEGED. - Reading your own app's signing information requires no permission.
- Images and files are temporarily authorized to the receiver via
ability.params.streamand the READ flag; no file permission is needed.
5.3 Configuration Not Required
- No callback
urisneed to be declared inskills; WorkBuddy does not call back into your app. - No need to handle WorkBuddy's return in
onNewWant.
6. Registration
It is recommended to register once in the main UIAbility's onCreate, and you must explicitly pass NativeShareTransport(context). If you want to share images, files, or thumbnails, also pass context.cacheDir:
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { WorkBuddyOpen, NativeShareTransport, ShareInitializationError,
ShareInitializationErrorCode } from '@workbuddy/open-sdk';
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
try {
WorkBuddyOpen.register('app_YOUR_REGISTERED_ID', 'key_YOUR_REGISTERED_KEY',
new NativeShareTransport(this.context), this.context.cacheDir);
} catch (error) {
if (error instanceof ShareInitializationError &&
error.code === ShareInitializationErrorCode.ALREADY_REGISTERED) {
// 本执行环境已注册,沿用首次配置
} else {
// Invalid appId / Invalid kid / Invalid caller identity / Invalid cache directory
}
}
}
}Registration rules:
- During
register, the SDK synchronously reads the app's bundleName, appIdentifier, and signing certificate fingerprint; you do not need to fill them in manually. cacheDirectorymust be an absolute path; normally passcontext.cacheDirdirectly. The SDK stores only this path string and does not hold a global Context.- If omitted, plain text and link sharing still work as usual;
- Sharing that requires an image, file, or thumbnail returns
FAILED / RESOURCE_UNAVAILABLE.
- Registration can succeed only once in the same execution environment. Any subsequent call throws
ShareInitializationError(code === ALREADY_REGISTERED), and the first configuration remains unchanged. Registration state is not shared across Workers. The SDK provides no unregister or reset. - A failed first registration leaves no state; you can retry after fixing the problem.
- Calling
sharebefore registration returnsFAILED / NOT_REGISTERED. - If
transportis not passed, a placeholder implementation is used and every share returnsFAILED / NOT_IMPLEMENTED.
7. Detect Whether WorkBuddy Is Installed
No registration is required; returns synchronously:
import { WorkBuddyOpen, AppInstallationStatus } from '@workbuddy/open-sdk';
const status: AppInstallationStatus = WorkBuddyOpen.checkAppInstallation();
// DETECTED:检出 workbuddy:// 的可访问处理者
// NOT_DETECTED:未检出;可能未安装、被禁用或版本未提供该入口
// UNKNOWN:查询失败,例如 querySchemes 未声明 workbuddy- Every call is a real-time query, does not cache the result, and does not launch WorkBuddy.
- Detecting
workbuddydoes not mean sharing is supported. Older WorkBuddy versions may register onlyworkbuddy; in that case installation detection returnsDETECTED, but the share capability check fails.
8. Guide Users to Download WorkBuddy
Call this when the user actively taps "Download WorkBuddy", passing the currently foreground UIAbilityContext:
import { common } from '@kit.AbilityKit';
import { WorkBuddyOpen } from '@workbuddy/open-sdk';
async function openStore(context: common.UIAbilityContext): Promise<void> {
try {
const accepted = await WorkBuddyOpen.openAppStore(context);
if (!accepted) {
// 应用市场不可用或拉起失败,由你决定提示文案
}
} catch (error) {
// 非预期异常
}
}- The SDK opens
store://appgallery.huawei.com/app/detail?id=com.tencent.workbuddyohosusingaction: 'ohos.want.action.appdetail'; no new permission or querySchemes is required. - Returning
trueonly means the system accepted the jump; it does not mean the user has downloaded and installed it. ABusinessErrorreturned by the system is converted tofalse; other unexpected exceptions are still thrown. - The SDK does not cache the Context, does not retry automatically, and does not fall back to a web page.
9. Verify the Integration
- Configure signing for the project (an unsigned HAP cannot be installed), then install an OpenSDK-capable WorkBuddy on a physical device and sign in.
- Run your app:
checkAppInstallation()should returnDETECTED. - Perform one text share;
shareshould returnHANDED_OFFand launch WorkBuddy. - In WorkBuddy, confirm that the text appears in the input box. If it does not, follow the troubleshooting checklist in Results and Error Codes to check bundleName, appIdentifier registration, and sign-in status.
10. Privacy and Compliance
- The SDK does not collect device identifiers, does not report data, and does not log shared content. On startup failure it records only a numeric error code, not content, URLs, file names, or signatures.
- The only identity information the SDK collects is your own app's bundleName, appIdentifier, and signing certificate fingerprint, which are passed to WorkBuddy with the share request to verify the Open Platform registration.
- The personal information processing rules and the official license agreement are pending release.
Developer Guide
Before reading this article, complete the integration, querySchemes configuration, and registration in the Integration Guide.
Basic Calls
WorkBuddyOpen.share(request) returns Promise<ShareResult>:
import { WorkBuddyOpen, TextShareRequest, ShareResult } from '@workbuddy/open-sdk';
async function shareText(): Promise<void> {
try {
const result: ShareResult = await WorkBuddyOpen.share(new TextShareRequest('分享内容'));
handle(result);
} catch (error) {
// 非预期错误
}
}ArkTS uses positional arguments. For all request types, the constructor parameter order is: content first, then the optional signature and metadata; for file requests, fileName and mimeType come next; suggestions comes last. To skip intermediate parameters, pass undefined for signature and new ShareMetadata() for metadata.
Share Text
const request = new TextShareRequest(
"季度复盘要点:\n1. 收入增长 12%\n2. 新增客户 30 家",
undefined, // signature
new ShareMetadata("季度复盘"), // metadata
["总结主要观点", "整理待办事项"], // suggestions
);
const result = await WorkBuddyOpen.share(request);| Parameter | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Cannot be empty or contain only whitespace; up to 64 KiB (UTF-8); cannot contain unpaired UTF-16 surrogate characters |
Share a Link
const request = new LinkShareRequest(
"https://www.example.com/article/123",
undefined,
new ShareMetadata("文章标题", "文章摘要"),
);
const result = await WorkBuddyOpen.share(request);| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | Yes | An absolute http / https URL with a host name, up to 16 KiB. The SDK does not rewrite the URL. For format requirements, see Mobile Sharing Overview |
Share an Image
const thumbnail =
thumbnailBytes === undefined
? undefined
: ShareMediaSource.fromBytes(thumbnailBytes);
const request = new ImageShareRequest(
ShareMediaSource.fromBytes(imageBytes), // 原始 PNG / JPEG 字节(ArrayBuffer)
undefined,
new ShareMetadata(undefined, undefined, thumbnail),
);
const result = await WorkBuddyOpen.share(request);| Parameter | Type | Required | Description |
|---|---|---|---|
image | ShareMediaSource | Yes | PNG / JPEG only, up to 20 MiB; each side ≤ 16,384 pixels, total pixels ≤ 40,000,000 |
- Use the original image data. Do not decode it into a
PixelMapand repackage it. Re-encoding changes the byte content and causes a digest mismatch when signatures are used. - The SDK identifies the format from the file header and does not transcode or compress.
- Internally, the SDK names the image
image.pngorimage.jpg, with the MIME typeimage/pngorimage/jpeg.
Share a File
import { fileUri } from "@kit.CoreFileKit";
const uri = fileUri.getUriFromPath(`${context.filesDir}/report.pdf`); // 必须是 file:// URI
const request = new FileShareRequest(
ShareMediaSource.fromFileUri(uri),
undefined,
new ShareMetadata(),
"2026Q3-复盘.pdf", // fileName
"application/pdf", // mimeType
);
const result = await WorkBuddyOpen.share(request);| Parameter | Type | Required | Description |
|---|---|---|---|
file | ShareMediaSource | Yes | Up to 100 MiB; cannot be an empty file |
fileName | string |undefined | No | |
mimeType | string |undefined | No |
Media Source ShareMediaSource
| Factory method | Use case | Description |
|---|---|---|
ShareMediaSource.fromBytes(bytes: ArrayBuffer) | Data in memory | Copies the data at construction time. Reading the bytes property also returns a copy |
ShareMediaSource.fromFileUri(uri: string) | A sandbox file, or a file with read access obtained through a Picker | Must start with file://. Sandbox paths can be converted with fileUri.getUriFromPath(path) |
- Construction does not read files or request permissions. The SDK uses
fileIoto read asynchronously only after the capability check passes. - Your app must already be able to read the URI. If the file does not exist, is unreadable, or permission is missing,
FAILED / RESOURCE_UNAVAILABLEis returned. - When using images, files, or thumbnails,
registermust be passedcacheDirectory, otherwiseFAILED / RESOURCE_UNAVAILABLEis returned. - The SDK generates a dedicated copy for this request in the app cache directory, then temporarily authorizes WorkBuddy through
ability.params.streamand the READ flag. The source file is not modified, and its path is not handed to WorkBuddy. - Do not modify or delete the source file before
sharereturns.
Title, Description, and Thumbnail ShareMetadata
new ShareMetadata(
"标题", // title,可选,最多 1 KiB
"描述", // description,可选,最多 4 KiB
ShareMediaSource.fromBytes(pngBytes), // thumbnail,可选,PNG / JPEG,最多 256 KiB
);- All four request types can carry
metadata; when omitted, it is empty. - The thumbnail and the original image are independent: the thumbnail cannot replace the original image, nor is it generated automatically from it.
- The current version of WorkBuddy only validates the thumbnail and does not display it.
Suggestions suggestions
new TextShareRequest("会议纪要……", undefined, new ShareMetadata(), [
"总结主要观点",
"整理待办事项",
"提炼关键结论",
]);- The type is
string[], defaulting to an empty array. The SDK keeps only the first 3 entries verbatim in order; duplicates and whitespace-only entries are also kept and occupy a slot. Readingrequest.suggestionsreturns a copy. - The SDK does not trim, truncate, or rewrite suggestion content. WorkBuddy displays at most the first 14 characters of each entry; when the user taps it, the content is appended to the input box.
- When signatures are used, the backend must compute digests for these 3 verbatim entries in order; see OpenSDK Signature Developer Guide.
Sharing with a Signature
import { SignaturePayload } from "@workbuddy/open-sdk";
// 从你自己的后台获取本次分享的签名包;参数顺序为 kid、message、nonce、timestamp、sig
const signature = new SignaturePayload(
payload.kid,
payload.message,
payload.nonce,
payload.timestamp,
payload.sig,
);
const result = await WorkBuddyOpen.share(
new TextShareRequest(text, signature, new ShareMetadata(), suggestions),
);kidmust be exactly the same as thekidused inregister, otherwise the SDK immediately returnsFAILED / INVALID_SIGNATURE. Apart from that, the SDK does not validate the signature content; WorkBuddy is responsible for verification.timestampis a string; do not convert it to a number.- The signature package is bound to the content of this request. Finalize the text, title, description, media, and suggestions before requesting a backend signature, and do not modify them afterward.
- The signature package has a short validity period (the server uses
timestamp, at most 300 seconds); obtain it right before sharing and do not cache it. - Once a signature is provided, WorkBuddy rejects the share if verification fails; it does not fall back to unsigned sharing.
Handling Share Results
import { ShareResult, ShareStatus, ShareErrorCode } from '@workbuddy/open-sdk';
function handle(result: ShareResult): void {
if (result.status === ShareStatus.HANDED_OFF) {
// 已拉起 WorkBuddy 并交出内容。不代表已到达输入框,也不代表用户已发送
return;
}
switch (result.errorCode) {
case ShareErrorCode.NOT_REGISTERED: break; // 未调用 register
case ShareErrorCode.NOT_IMPLEMENTED: break; // register 时没有传 NativeShareTransport
case ShareErrorCode.UNAVAILABLE: break; // 检查 entry 的 querySchemes 是否声明 workbuddy-opensdk
case ShareErrorCode.UNSUPPORTED_CAPABILITY: break; // WorkBuddy 未安装或版本不支持,可引导 openAppStore
case ShareErrorCode.RESOURCE_UNAVAILABLE: break; // 媒体不可读,或 register 未传 cacheDirectory
default: break;
}
}result.requestIdis a UUID generated by the SDK for this call, used only to correlate logs within your app; it is not a server-side ID.ShareStatus.CANCELLEDis a reserved status that the current built-in transport does not return. The ArkTS version also has no entry point for cancelling a share.- For the full list of error codes, see Results and Error Codes.
Notes
- Call in the foreground: the SDK calls
startAbilitywith theUIAbilityContextpassed at registration to launch WorkBuddy; call it when the app is in the foreground and triggered by a user action. - Implicit launch: the SDK uses
ohos.want.action.viewDataandworkbuddy-opensdk://share?...to implicitly match a receiver without specifying a bundleName. If multiple apps on the device declare this entry, the system decides or lets the user choose. - Capability check: before every share, the SDK uses
canOpenLink('workbuddy-opensdk://share')to check. It only shows that some app can handle this entry; it cannot verify the other party's identity or version. - Copy reclamation: the SDK keeps media copies for at most 4 requests at a time, each for up to 10 minutes. When exceeded, it reclaims the earliest request; if WorkBuddy has not finished reading, the read fails. Avoid sharing multiple large files in rapid succession.
- Repeated calls: every
sharegenerates a newrequestId. With signatures, WorkBuddy deduplicates byappId + nonce; sharing the same signature package again is ignored as a duplicate request. Every new share requires a new signature package signed by the backend.
Mobile Sharing Overview
After integrating the WorkBuddy Open SDK, your app can share text, links, images, and files to WorkBuddy. WorkBuddy places the received content into the input box draft or as an attachment, but does not send it automatically; the user confirms, edits, and sends it themselves.
Supported Share Types
| Type | Request class | Required content | Optional content | Effect in WorkBuddy |
|---|---|---|---|---|
| Text | TextShareRequest | text | Title, description, thumbnail, suggestions | Filled into the input box of the current foreground conversation |
| Link | LinkShareRequest | url (HTTP / HTTPS) | Same as above | Displayed in the input box as a removable link card |
| Image | ImageShareRequest | image (raw PNG / JPEG data or file) | Same as above | Enters image preview or attachment |
| File | FileShareRequest | file (any file) | File name, MIME type hint, and the above content | Enters file preview or attachment |
All four request types share the following optional parameters:
| Parameter | Description |
|---|---|
signature | A signature package generated by the backend, optional; see "Two Authorization Modes" below |
metadata.title / metadata.description | Display title and description. The link card shows title, or the URL if it is not set |
metadata.thumbnail | Thumbnail, PNG / JPEG, independent of the original image; cannot be used to replace it |
suggestions | Suggestion list; the SDK keeps only the first 3 entries |
Display Rules on the WorkBuddy Side
Text
- Filled in only when the current foreground input box is empty. An existing draft is neither overwritten nor appended to.
- Content beyond 20,000 characters is truncated.
- No new conversation is created, and nothing is sent automatically.
Links
- Displayed as a link card showing the
titleif present, otherwise the URL, with the subtitle "Web Link". The card does not show the description or thumbnail. - The link card can coexist with text the user has already entered, and the user can delete it.
- The URL is not appended to the message body. When the user sends, the link is carried only once as a card attachment.
Images and Files
- Follows WorkBuddy's existing file sharing flow, entering preview or attachment, and is likewise subject to file type filtering, image compression, and attachment size limits.
- Pass a
fileNamewith the correct extension for files. If omitted, the file name isfile, which may be rejected by file type filtering. - The SDK allows a single file up to 100 MiB, but WorkBuddy has business limits such as 20 MiB per file when inserting an attachment; larger files may fail to insert.
- ZIP files are treated as ordinary attachments.
Suggestions
- Displayed vertically beside the input box that adopted the shared content. Each entry shows at most the first 14 characters (counted as user-visible characters, with one full emoji counted as one); entries that are empty after truncation are not displayed.
- When the user taps one, the suggestion is appended to the message body for the user to edit and send.
- If the shared content was not actually adopted (for example, text was not filled in because the input box already had a draft), the suggestions are not displayed either.
Two Authorization Modes
Signatures are optional. WorkBuddy chooses the verification method based on whether the request contains a signature:
| Unsigned mode | Signed mode | |
|---|---|---|
| Client | Does not pass signature | Passes the SignaturePayload generated by the backend |
| Backend | Not required | Generates a signature package for every share |
| WorkBuddy verification | Queries the Open Platform registration information and checks appId against the terminal identity (package name / Bundle ID / bundleName, etc.) | Calls the Open Platform signature verification API, checks the terminal identity, and compares content digests |
| What it proves | The identity reported by the request matches the registration | The content matches what the backend signed and is within the validity period |
| On failure | Rejects | Rejects, with no fallback to unsigned mode |
Both modes cannot prove that the share was definitely initiated by your app: the identity fields are self-reported by the SDK, and a signature package may be replayed within its validity period. Signature verification is also not content moderation.
For how to generate the signature package, see OpenSDK Signature Developer Guide.
Size and Format Limits
Reaching the upper limit is allowed; exceeding it makes share return FAILED / PAYLOAD_TOO_LARGE.
| Field / resource | Limit | Calculation |
|---|---|---|
| Text | 64 KiB | UTF-8 byte count |
| Link | 16 KiB | UTF-8 byte count |
| Title / description | 1 KiB / 4 KiB | UTF-8 byte count |
| Thumbnail | 256 KiB | Raw byte count |
| Image | 20 MiB | Raw byte count |
| File | 100 MiB | Raw byte count |
| File name / MIME hint | 255 / 127 bytes | UTF-8 byte count |
| Image and thumbnail dimensions | Each side ≤ 16,384 pixels, total pixels ≤ 40,000,000 | Original encoded dimensions, ignoring EXIF rotation |
| Suggestions | At most 3 entries kept | Subject to the overall packaging budget together with other fields (JSON 1 MiB, URL 1.5 MiB) |
Format requirements; FAILED / INVALID_REQUEST is returned when they are not met:
- Text: cannot be empty or contain only whitespace. The SDK does not trim or rewrite any content.
- Link: must be an absolute
http/httpsURL with a host name. It must not contain whitespace, control characters, backslashes, or a username/password; percent escapes must be valid, and the port must be in 0–65535. The host name may contain only ASCII; convert internationalized domain names to Punycode first. Paths and query parameters may contain Unicode. - File name: cannot be empty,
., or.., and cannot contain path separators or control characters. The file name is only for display and is never used as a storage path. - MIME hint:
type/subtypeformat without parameters. It is only a hint; the SDK does not verify the file's real format. - Image / thumbnail: only PNG and JPEG are supported. The SDK identifies the format from the file header and does not transcode. Unsupported formats return
UNSUPPORTED_MEDIA_TYPE. - Empty media: empty in-memory data returns
INVALID_REQUEST. An empty local file returnsINVALID_REQUESTafter being read.
The Process of One Share
sharegenerates this call'srequestId(UUID). A new ID is generated for every call, even if the same request object is reused.- Checks whether registration has completed and whether
signature.kidmatches thekidused at registration. - Validates the request content and sizes.
- Checks whether WorkBuddy on the device supports OpenSDK sharing; if not, no media is read.
- Reads the media, computes SHA-256, and generates a dedicated temporary copy for this request.
- Launches WorkBuddy, hands over the content, and returns
HANDED_OFF. - WorkBuddy completes the subsequent processing outside your app: checks sign-in status, queries registration information or verifies the signature, validates the media, and finally places it in the input box or as an attachment. If the user is not signed in, it waits for the user to sign in first, with a time limit.
The result of step 7 is not returned to your app. HANDED_OFF only means step 6 succeeded.
Temporary Files and Resources
- For each share, the SDK generates media copies in its own cache directory, does not modify the original file, and does not hand the original path to WorkBuddy.
- Android / HarmonyOS grant WorkBuddy temporary read-only URI access to the copies; copies are kept for at most 10 minutes and 4 requests, and the earliest request is reclaimed when exceeded.
- iOS: media with an original size below 450 KiB (460,800 bytes) is passed directly with the jump link; media at or above that size is passed as a file via the local clipboard (not synced across devices, expiring after 10 minutes). The SDK clears the content it wrote only when the clipboard content has not been modified by others.
- When sharing multiple large files rapidly in succession, earlier requests may become unreadable because their copies have been reclaimed; avoid batch sharing all at once.
Unsupported Capabilities
- Forwarding content to other contacts or teams in WorkBuddy, or selecting a target conversation, is not supported.
- Sending messages automatically or creating new conversations is not supported.
- No delivery receipts, result callbacks, or switch-backs are provided.
- Dedicated card types such as video and music are not supported. Video and audio can be shared as ordinary files.
OpenSDK Signature Developer Guide
This article is intended for backend developers of integrating parties and explains how to generate a signature package SignaturePayload for one share. Signatures are optional; if you do not use signatures, you can skip this article and refer to Mobile Sharing Overview.
1. Purpose of the Signature
For a signed share, WorkBuddy calls the Open Platform signature verification API to confirm three things:
- The signature package was issued by the backend holding the private key corresponding to
kid, and is within its validity period; - The terminal identity in the request (package name and certificate fingerprint / Bundle ID / bundleName, etc.) is consistent across the Open Platform registration information and the signature manifest;
- The text, link, media, title, description, and suggestions actually received are byte-for-byte consistent with the digests signed by the backend.
If any of these is not satisfied, WorkBuddy rejects the share, with no fallback to unsigned mode.
Signatures cannot prove the following:
- That the call was definitely initiated by your app: a signature package can be replayed if obtained by others within its validity period;
- Content compliance: a signature is not content moderation.
2. Preparation
- Generate an RSA key pair on the backend. Keep the private key only on the backend; it must not be distributed to clients or packaged into the app.
- Register the public key for the app on the WorkBuddy Open Platform and obtain the corresponding
kid. - When the client calls
WorkBuddyOpen.register, pass the samekid. If thekidin the signature package does not match the registered value, the SDK immediately returnsFAILED / INVALID_SIGNATURE. - Confirm that the terminal identity has been registered on the Open Platform; see the "Register Your App on the Open Platform" section of each platform's Integration Guide.
3. Overall Flow
sequenceDiagram
participant App as 接入方 App(SDK)
participant Server as 接入方后台
participant WB as WorkBuddy App
participant OP as WorkBuddy 开放平台
App->>Server: 1. 请求签名(本次分享内容或其标识)
Server->>Server: 2. 构造业务清单 → message
Server->>Server: 3. 生成 nonce、timestamp,用私钥计算 sig
Server-->>App: 4. 返回 kid / message / nonce / timestamp / sig
App->>WB: 5. WorkBuddyOpen.share(request + signature),返回 HANDED_OFF
WB->>OP: 6. 用户登录后,提交 appId + 五个签名字段验签
OP-->>WB: 7. 返回验签结果和登记身份
WB->>WB: 8. 核对身份与内容摘要,通过后放入输入框 / 附件
The SDK passes the five fields verbatim to WorkBuddy without decoding, validating, or re-signing them. Steps 6–8 happen inside WorkBuddy, and the result is not returned to your app.
4. Signature Package Fields
The signature package returned by the backend to the client contains the following 5 fields, all strings. The client uses them to construct a SignaturePayload:
| Field | Description | Constraints |
|---|---|---|
kid | Key identifier | Exactly the same as the value registered on the Open Platform and passed to register on the client; case and leading/trailing spaces must not change |
message | The UTF-8 bytes of the business manifest JSON, encoded with standard Base64 (with = padding) | 1–16,384 bytes after decoding; at most 21,848 characters after encoding; must be canonical encoding |
nonce | Random string for this signature | 16–64 characters, containing only ASCII letters, digits, _, -. Must be regenerated for every share |
timestamp | Signing time, Unix timestamp in seconds | Decimal string, 1–10 digits, no leading zeros. Must remain a string type |
sig | RSA signature result | Signature bytes encoded with standard Base64 |
appId is not in the signature package. The SDK automatically passes the appId provided at register to WorkBuddy together with these 5 fields; the backend uses the same appId when generating the signature.
5. Generation Steps
5.1 Finalize the shared content
The signature is bound to the content actually sent. Finalize the text, link, title, description, media files, thumbnail, and suggestions before generating the signature. After signing, if the client modifies any of them (including re-encoding an image or replacing a file), WorkBuddy rejects the share due to a digest mismatch.
It is recommended that the backend compute the digests from content it holds itself. If digests are reported by the client, the signature can only prove that the backend agreed to this share; it cannot prevent the client from tampering with the content.
5.2 Construct the business manifest
The business manifest is a JSON object whose field set, values, and types must match the content the SDK actually sends. Field order does not affect verification.
| Field | Type | Required | Description |
|---|---|---|---|
format | string | Yes | Fixed to "workbuddy.share.v1" |
clientPlatform | string | Yes | "android", "ios", or "harmonyos", matching the client platform initiating the share |
type | string | Yes | "TEXT", "LINK", "IMAGE", or "FILE" |
callerIdentity | object | Yes | Terminal identity; see the table below |
payload | object | Yes | Content digest; see below |
metadata | object | Yes | Digests of the title, description, and thumbnail; see below |
suggestions | array | No | Suggestion digests; omit this field when there are no suggestions |
callerIdentity
The values must match those automatically collected by the SDK at registration, and also match the Open Platform registration information:
| Platform | Structure | Description |
|---|---|---|
| Android | {"packageName": "...", "certificateFingerprints": ["..."]} | The fingerprint is 64-character uppercase hexadecimal without colons. The array must match all current signers collected by the SDK; usually there is only one |
| iOS | {"bundleId": "..."} | Only the Bundle ID, no Team ID |
| HarmonyOS | {"bundleName": "...", "appIdentifier": "...", "certificateFingerprint": "..."} | The fingerprint is 64-character uppercase hexadecimal without colons |
For how to obtain the actual values on each platform, see the corresponding Integration Guide (AndroidIdentity.capture, IOSCallerIdentity.capture, HarmonyCallerIdentity.capture).
Digest Format
All text fields are represented by a digest object:
{"byteCount": <原始 UTF-8 字节数>, "sha256": "<原始 UTF-8 字节的 SHA-256,64 位小写十六进制>"}
- Compute over the original bytes; do not trim whitespace, apply Unicode normalization, convert newlines, or rewrite URLs.
- The empty string
""must also have a digest computed (byteCountis 0). It is not equivalent to "not set" (JSONnull).
payload
| type | payload structure |
|---|---|
TEXT | Digest object of the text |
LINK | Digest object of the URL string |
IMAGE | {"media": <media descriptor>} |
FILE | {"media": <media descriptor>} |
The media descriptor contains exactly the following 6 fields, computed from the original bytes of the media file:
| Field | IMAGE | FILE |
|---|---|---|
fileName | "image.png" or "image.jpg", according to the actual format | The fileName passed by the client; "file" if omitted |
mimeType | "image/png" or "image/jpeg" | The mimeType passed by the client; "application/octet-stream" if omitted |
byteCount | Original byte count (integer) | Same as left |
sha256 | SHA-256 of the original bytes, 64-character lowercase hexadecimal | Same as left |
width / height | Pixel width and height of the original encoding (integers), ignoring EXIF rotation | null |
metadata
| Field | Description |
|---|---|
title | Digest object of the title; null if not set |
description | Digest object of the description; null if not set |
thumbnail | A media descriptor when a thumbnail exists, with fileName of "thumbnail.png" or "thumbnail.jpg" and mimeType and dimensions filled in according to the actual format; omit this field when there is no thumbnail, do not write null |
All four request types can carry a thumbnail. Adding or removing a thumbnail also participates in verification.
Suggestions
When suggestions exist, add suggestions at the top level of the manifest: in the order passed by the client, list the digest objects of the first 3 verbatim entries actually kept by the SDK.
- Duplicates, whitespace-only entries, and portions beyond 14 characters must all be computed over the verbatim text; do not truncate them first according to WorkBuddy's display rules.
- Do not sign the 4th and later suggestions; the SDK does not send them.
- Omit this field when there are no suggestions (an empty array
[]is also treated as "no suggestions"). - Any change to the addition, removal, order, or text of suggestions causes WorkBuddy to reject the share.
5.3 Encode message
Serialize the manifest JSON to UTF-8 bytes, then apply standard Base64 encoding (character set A–Z a–z 0–9 + /, with = padding, no line breaks). Note that this is not URL-safe Base64.
The decoded manifest is at most 16,384 bytes. The manifest contains only digests, not the original text, so even a 64 KiB text fits.
5.4 Generate nonce and timestamp
nonce: regenerate with a secure random number for every share, for example 32 hexadecimal characters.timestamp: take the backend's current Unix seconds and convert to a string.
The WorkBuddy Open Platform validity window is -30 ≤ server current time − timestamp ≤ 300 seconds; keep the backend clock accurate. The client should obtain the signature package right before sharing and not cache it in advance.
5.5 Compute sig
Using the RSA private key corresponding to kid, compute the signature according to the RS256 signing flow specified by the Open Platform signature verification API, then apply standard Base64 encoding to the signature bytes to obtain sig.
To be added: the rules for assembling the string to be signed (the fields involved, their order, and separators) are subject to the WorkBuddy Open Platform signature verification API documentation and will be added before this article is officially published. Neither the SDK nor the WorkBuddy client participates in this computation.
5.6 Return to the client
Return the 5 fields verbatim to the client; the client uses them to construct a SignaturePayload and call share, as described in the "Sharing with a Signature" section of each platform's Developer Guide.
6. Examples
6.1 iOS text sharing (with a title and two suggestions)
Client request:
TextShareRequest(
text: "分享内容",
signature: signature,
metadata: ShareMetadata(title: "示例标题"),
suggestions: ["总结主要观点", "整理待办事项"]
)
When the host Bundle ID is com.example.host, the corresponding business manifest is:
{
"format": "workbuddy.share.v1",
"clientPlatform": "ios",
"type": "TEXT",
"callerIdentity": {"bundleId": "com.example.host"},
"payload": {
"byteCount": 12,
"sha256": "a840e8381cf382d9ffa5717d9588c214fe605d9c2061afb2f95af4e96fab396e"
},
"metadata": {
"title": {
"byteCount": 12,
"sha256": "7bcb60020d757ee04d230f4c50eb23734444559df5330cc780d733ed6852097c"
},
"description": null
},
"suggestions": [
{"byteCount": 18, "sha256": "945c7e05efe6a737741da070b08e0c09590f27e4c62782b4b1ea7d0aabef7e68"},
{"byteCount": 18, "sha256": "b2ef5682224e068c543a09ef6182e92109dd500d1413d0cc9776100a11245a4e"}
]
}
After compact serialization (no spaces) and standard Base64 encoding, the resulting message is:
eyJmb3JtYXQiOiJ3b3JrYnVkZHkuc2hhcmUudjEiLCJjbGllbnRQbGF0Zm9ybSI6ImlvcyIsInR5cGUiOiJURVhUIiwiY2FsbGVySWRlbnRpdHkiOnsiYnVuZGxlSWQiOiJjb20uZXhhbXBsZS5ob3N0In0sInBheWxvYWQiOnsiYnl0ZUNvdW50IjoxMiwic2hhMjU2IjoiYTg0MGU4MzgxY2YzODJkOWZmYTU3MTdkOTU4OGMyMTRmZTYwNWQ5YzIwNjFhZmIyZjk1YWY0ZTk2ZmFiMzk2ZSJ9LCJtZXRhZGF0YSI6eyJ0aXRsZSI6eyJieXRlQ291bnQiOjEyLCJzaGEyNTYiOiI3YmNiNjAwMjBkNzU3ZWUwNGQyMzBmNGM1MGViMjM3MzQ0NDQ1NTlkZjUzMzBjYzc4MGQ3MzNlZDY4NTIwOTdjIn0sImRlc2NyaXB0aW9uIjpudWxsfSwic3VnZ2VzdGlvbnMiOlt7ImJ5dGVDb3VudCI6MTgsInNoYTI1NiI6Ijk0NWM3ZTA1ZWZlNmE3Mzc3NDFkYTA3MGIwOGUwYzA5NTkwZjI3ZTRjNjI3ODJiNGIxZWE3ZDBhYWJlZjdlNjgifSx7ImJ5dGVDb3VudCI6MTgsInNoYTI1NiI6ImIyZWY1NjgyMjI0ZTA2OGM1NDNhMDllZjYxODJlOTIxMDlkZDUwMGQxNDEzZDBjYzk3NzYxMDBhMTEyNDVhNGUifV19
6.2 HarmonyOS file sharing (empty title, with a thumbnail)
The client shares a 23-byte report.txt with mimeType of text/plain, an empty string "" as the title, and a 1×1 PNG thumbnail:
{
"format": "workbuddy.share.v1",
"clientPlatform": "harmonyos",
"type": "FILE",
"callerIdentity": {
"bundleName": "com.example.host",
"appIdentifier": "host_app_identifier",
"certificateFingerprint": "ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB"
},
"payload": {
"media": {
"fileName": "report.txt",
"mimeType": "text/plain",
"byteCount": 23,
"sha256": "4a1a009b608d793671faf5f00a511fedf0778ac65d5af0aef87ac402251aeac4",
"width": null,
"height": null
}
},
"metadata": {
"title": {
"byteCount": 0,
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"description": null,
"thumbnail": {
"fileName": "thumbnail.png",
"mimeType": "image/png",
"byteCount": 68,
"sha256": "7ac2abfce2be8b46dd9826d597d94edeefc1570b4a992622721b90a1850e3ee9",
"width": 1,
"height": 1
}
}
}
Note: the digest of the empty title "" is the SHA-256 of the empty byte string, not null. There are no suggestions, so suggestions is omitted.
7. Backend Reference Code
The following Python example shows how to construct the manifest and message; implement sig computation according to section 5.5:
import base64
import hashlib
import json
import secrets
import time
def digest(text):
data = text.encode("utf-8")
return {"byteCount": len(data), "sha256": hashlib.sha256(data).hexdigest()}
def optional_digest(text):
return None if text is None else digest(text)
def media_descriptor(data, file_name, mime_type, width=None, height=None):
return {
"fileName": file_name,
"mimeType": mime_type,
"byteCount": len(data),
"sha256": hashlib.sha256(data).hexdigest(),
"width": width,
"height": height,
}
def build_text_manifest(platform, caller_identity, text, title=None, description=None, suggestions=None):
manifest = {
"format": "workbuddy.share.v1",
"clientPlatform": platform, # "android" / "ios" / "harmonyos"
"type": "TEXT",
"callerIdentity": caller_identity, # 与开放平台登记、SDK 采集一致
"payload": digest(text),
"metadata": {"title": optional_digest(title), "description": optional_digest(description)},
}
kept = (suggestions or [])[:3] # 与 SDK 一致,只保留前三条原文
if kept:
manifest["suggestions"] = [digest(s) for s in kept]
return manifest
def build_signature_payload(kid, manifest):
message = base64.b64encode(json.dumps(manifest, ensure_ascii=False, separators=(",", ":")).encode("utf-8")).decode("ascii")
nonce = secrets.token_hex(16) # 32 个字符
timestamp = str(int(time.time()))
sig = sign_by_platform_rule(kid, message, nonce, timestamp) # 按开放平台验签接口规定的 RS256 流程实现
return {"kid": kid, "message": message, "nonce": nonce, "timestamp": timestamp, "sig": sig}8. WorkBuddy Verification Rules
| Check item | Rule | On failure |
|---|---|---|
| kid | Exactly matches the kid of register | The SDK immediately returns FAILED / INVALID_SIGNATURE and does not launch WorkBuddy |
| Field completeness | All 5 fields are non-empty strings, with no extra fields | WorkBuddy rejects |
| Time window | -30 ≤ now − timestamp ≤ 300 | WorkBuddy rejects |
| Signature verification | The Open Platform verifies sig with the public key corresponding to kid | WorkBuddy rejects |
| Usage count | The same appId + nonce can be successfully verified at most 3 times on the Open Platform | WorkBuddy rejects after the limit is exceeded |
| Local deduplication | On the same device, the same appId + nonce is adopted only once | Ignored as a duplicate request |
| Terminal identity | Registration information, the identity in the request, and the identity in the manifest are consistent | WorkBuddy rejects |
| Content digest | The content actually received matches the manifest item by item | WorkBuddy rejects |
WorkBuddy verifies the signature only once per request and does not retry automatically; a failed verification does not switch to unsigned mode.
9. FAQ
Q: The SDK returned HANDED_OFF, but there is no content in WorkBuddy?
It was rejected on the WorkBuddy side, and the result is not returned. Common causes: an expired signature (the client cached the signature package, or the backend clock is skewed); a manifest inconsistent with the actual content (an image was re-encoded, a file name was omitted or differs from the manifest, the title used null instead of "", or suggestions were signed after truncation); terminal identity inconsistent with registration (Debug and Release certificates differ); or a reused nonce.
Q: I want to share the same content twice; can I reuse the signature package?
No. Every share requires a new nonce and a new signature package; a reused signature package is ignored as a duplicate request.
Q: Do I need to sign requestId?
No. requestId is a local identifier generated by the SDK for each call and does not participate in signing.
Q: Does the manifest need to include appId?
No. The appId is submitted to WorkBuddy by the SDK together with the signature package; the backend simply uses the same appId when signing.
10. Security Recommendations
- Keep the private key only on the backend and restrict access to it; it must not appear in client code, configuration, or installation packages.
- Issue a signature package only when the user actually initiates a share, and complete business authentication on the backend before issuing it.
- Do not log complete signature packages.
- A signature package is a short-lived authorization credential and may be replayed within its validity period; do not treat it as the only security measure.
SDK Version Notes and Resource Downloads
Basic Information
| Platform | SDK name | Version | Runtime environment | Integration documentation |
|---|---|---|---|---|
| Android | WorkBuddy Share SDK (Android) | 0.1.0 | Android 6.0 (API 23) and above; JDK 17; compileSdk 35 | Android Integration Guide and Developer Guide |
| iOS | WorkBuddy Share SDK (iOS) | 0.1.0 | iOS 15.0 and above | iOS Integration Guide and Developer Guide |
| HarmonyOS | WorkBuddy Share SDK (HarmonyOS) | 0.1.0 | HarmonyOS 6.0.0 (API 20) and above | HarmonyOS Integration Guide and Developer Guide |
SDK introduction: A software development kit that provides apps developed and operated by developers with capabilities such as sharing content to WorkBuddy. After a user actively selects text, a link, an image, or a file in the app, the SDK hands the content to the local WorkBuddy client and pre-fills it into the conversation box for the user to confirm and send; the content is handed over locally on the device only and is not transmitted over the network.
Service provider: Tencent Cloud Computing (Beijing) Co., Ltd.
Personal information processing rules: "WorkBuddy Share SDK Personal Information Protection Rules"
Compliance usage instructions: "WorkBuddy Share SDK Compliance Usage Guide"
Resource Downloads
v0.1.0 development toolkit and sample projects:
| Platform | SDK development toolkit | Sample project |
|---|---|---|
| Android | WorkBuddyOpenSDK-Android-0.1.0.zip (local Maven repository: AAR, sources JAR, POM) Download | WorkBuddyOpenDemo-Android-0.1.0.zip Download |
| iOS | WorkBuddyOpenSDK-0.1.0.zip (XCFramework static library, supporting SPM and CocoaPods) Download | WorkBuddyOpenDemo-ios.zip (contains both SPM and CocoaPods projects) Download |
| HarmonyOS | workbuddy-open-sdk-0.1.0.har (pure ArkTS implementation compiled in Release mode) Download | workbuddy-open-sdk-demo-0.1.0.zip Download |
Version Information
Android
| Version | Updates |
|---|---|
| v0.1.0 | First release; supports sharing four content types: text, link, image, and file; validates the package name and signing certificate fingerprint at registration; supports installation detection and obtaining the official website URL; supports signature parameter passthrough; returns share status and error codes. |
iOS
| Version | Updates |
|---|---|
| v0.1.0 | First release; supports sharing four content types: text, link, image, and file; validates the Bundle ID at registration; supports installation detection and App Store navigation; supports signature parameter passthrough; returns share status and error codes; provides a privacy manifest. |
HarmonyOS
| Version | Updates |
|---|---|
| v0.1.0 | First release; supports sharing four content types: text, link, image, and file; validates BundleName, appIdentifier, and the certificate fingerprint at registration; supports installation detection and App Market navigation; supports signature parameter passthrough; returns share status and error codes. |
Results and Error Codes
ShareResult
WorkBuddyOpen.share returns ShareResult, with identical fields across all three platforms:
| Field | Type | Description |
|---|---|---|
requestId | String | A UUID generated by the SDK for this call, used only to correlate logs within your app; not a server-side ID |
status | ShareStatus | The status of this call |
errorCode | ShareErrorCode? | Has a value only when status is FAILED |
The raw values of the enums are the same across the three platforms. Swift uses lower camel case (e.g. .handedOff, .notRegistered), and rawValue matches the table below.
ShareStatus
| Value | Meaning |
|---|---|
HANDED_OFF | The system has accepted launching WorkBuddy and the content has been handed over. Does not mean signature verification passed, the content entered the input box, or the user has sent it |
FAILED | No content was handed over this time; see errorCode for the reason |
CANCELLED | A reserved status that the current built-in NativeShareTransport does not return. When a call is cancelled, Android throws CancellationException, iOS throws CancellationError; HarmonyOS has no cancellation entry point |
ShareErrorCode
| Error code | Meaning | Common causes | Suggested action |
|---|---|---|---|
NOT_REGISTERED | Not registered | register was not successfully called before share | Register at app startup |
NOT_IMPLEMENTED | Share channel not enabled | NativeShareTransport was not passed at register | Pass NativeShareTransport explicitly at registration; it cannot be changed after registration, so the process must be restarted |
INVALID_REQUEST | Invalid request parameters | Text is empty or whitespace-only; URL is invalid; file name or MIME format is wrong; media is empty; the ShareRequest base class was used directly; a HarmonyOS file URI does not start with file:// | Fix the parameters according to the format requirements |
INVALID_SIGNATURE | Signature package does not match registration information | signature.kid does not match the kid of register, or the signature field format does not meet packaging requirements | Check kid. This is not a verification result, the SDK performs no cryptographic verification |
PAYLOAD_TOO_LARGE | Size limit exceeded | Text, link, title, description, or media exceeds the limit; image dimensions exceed the limit; overall packaging exceeds the budget | Compress the content or share it as a file instead |
UNSUPPORTED_MEDIA_TYPE | Unsupported media format | Image or thumbnail is not PNG / JPEG, or dimensions cannot be read | Use raw PNG / JPEG data; use FileShareRequest for other formats |
RESOURCE_UNAVAILABLE | Media unreadable | File does not exist, no read permission, or the URI has expired; HarmonyOS register was not passed cacheDirectory; temporary copy creation failed or the copy has been reclaimed | Confirm read permission; on HarmonyOS pass context.cacheDir at registration |
UNAVAILABLE | Unable to confirm share capability | iOS: LSApplicationQueriesSchemes does not declare workbuddy-opensdk. Android: WorkBuddy is not installed, not visible, has not declared the protocol, or the version number cannot be parsed. HarmonyOS: querySchemes does not declare workbuddy-opensdk, or the system query failed | Check the query allowlist; on Android check whether the SDK-merged <queries> was removed; guide the user to install WorkBuddy |
UNSUPPORTED_CAPABILITY | WorkBuddy does not support this share | iOS / HarmonyOS: the workbuddy-opensdk entry was not detected (not installed or version too old). Android: WorkBuddy versionName is lower than 1.0.0. It may also be a custom ShareRequest subclass | Guide the user to install or upgrade WorkBuddy (openAppStore is available on iOS / HarmonyOS) |
TRANSPORT_FAILURE | Failed to launch WorkBuddy | The system refused to open (iOS open returned false, HarmonyOS startAbility failed); Android permission exception or Intent too large; the requestId returned by transport does not match this call | Make sure the app is in the foreground and retry later |
Registration Exceptions
When register fails, it throws an exception synchronously and does not return a ShareResult. Registration exceptions are independent of share error codes.
| Case | iOS (ShareInitializationError) | Android | HarmonyOS |
|---|---|---|---|
| Duplicate registration | .alreadyRegistered | ShareInitializationException, code == ALREADY_REGISTERED (inherits from IllegalStateException) | ShareInitializationError, code === ALREADY_REGISTERED |
Invalid appId format | .invalidAppId | IllegalArgumentException("Invalid appId") | Error('Invalid appId') |
Invalid kid format | .invalidKid | IllegalArgumentException("Invalid kid") | Error('Invalid kid') |
| Unable to read host identity | .unavailableBundleId (unable to read the Bundle ID) | IllegalStateException (unable to read the signing certificate) | An exception thrown by the system API |
| Invalid host identity format | .invalidIdentity | IllegalArgumentException (invalid package name or fingerprint format) | Error('Invalid caller identity') |
| Invalid cache directory | — | — | Error('Invalid cache directory') (not an absolute path) |
On duplicate registration, the SDK gives priority to throwing the "duplicate registration" exception and does not validate the parameters passed the second time. The first configuration remains unchanged.
Installation Detection Result AppInstallationStatus
| Value | Meaning |
|---|---|
DETECTED | A stable entry for WorkBuddy was detected (package visibility on Android; workbuddy:// can be opened on iOS / HarmonyOS). Does not mean sharing is supported, the user is signed in, or content will be delivered |
NOT_DETECTED | Not detected. This cannot prove the app is definitely uninstalled; system visibility restrictions can also cause this result |
UNKNOWN | Unable to query, for example iOS / HarmonyOS has not declared the workbuddy query allowlist, or the system query failed |
Troubleshooting When Content Does Not Reach WorkBuddy
If share returns HANDED_OFF but no content appears in WorkBuddy, the request was rejected on the WorkBuddy side, and this result is not returned to your app. Check the following one by one:
- Sign-in status: when WorkBuddy is not signed in, it holds the request temporarily and waits for the user to sign in. A request is valid for about 5 minutes: for unsigned requests, counted from when WorkBuddy receives it; for signed requests, counted from the signature's
timestamp; it is discarded after the timeout. - appId: whether it is an approved application.
- Terminal registration information:
- Android: whether the package name and signing certificate SHA-256 fingerprint match the actual installed package. Debug and Release certificates differ, and the fingerprint also changes after app store re-signing.
- iOS: whether the official Bundle ID has been registered.
- HarmonyOS: whether bundleName and appIdentifier match the current signing; when signatures are used, also check the certificate fingerprint.
- Signature (if any): see OpenSDK Signature Developer Guide.
- Text not filled in: WorkBuddy fills in text only when the foreground input box is empty; an existing draft is not overwritten.
- File not appearing: if the file name lacks an extension or the type is unsupported, it may be rejected by WorkBuddy's file type filter; attachments over 20 MiB may fail to insert.
- Large files:
- iOS: the clipboard was overwritten after sharing but before WorkBuddy read it;
- Android / HarmonyOS: more than 4 media requests were shared in a short period, so earlier copies have been reclaimed.
- Duplicate sharing: duplicate events with the same signature package (same
nonce) or the samerequestIdare ignored as duplicate requests.
WorkBuddy Share SDK Compliance Usage Guide
To help developers and operators using the WorkBuddy Share SDK (hereinafter "this SDK") (hereinafter "you") integrate and use this SDK in compliance with the provisions of laws, regulations, policies, and standards on personal information protection, the WorkBuddy Open Platform (hereinafter "we") has formulated this guide so that you can meet the corresponding compliance requirements while using this SDK. Please read and understand the contents of this guide fully before integrating and using this SDK.
I. Integrate or Upgrade to the Latest SDK Version That Meets New Regulatory Requirements
We attach great importance to the SDK's feature optimization, personal information security, and protection, and will upgrade and iterate SDK versions in due course to improve product security and stability and ensure compliance with the latest compliance requirements of relevant laws, regulations, regulators, and standards. We strongly recommend that you upgrade to the latest SDK version so as to ensure normal use of the latest SDK features and avoid adverse effects caused by untimely updates (for example, the APP being publicly reported or removed from stores).
After an SDK update, we will promptly remind you of the changes through official website announcements, site messages, email, or other appropriate means so that you can learn about the latest SDK version information in time. You can also visit the WorkBuddy Open Platform (https://open.workbuddy.cn/) to obtain the latest SDK version.
II. Disclose Third-Party SDK Information in the APP Privacy Policy
Please ensure that the APP you develop or operate is equipped with a "Privacy Policy" text that meets regulatory requirements, and explicitly inform end users that your APP integrates third-party SDK services. You should add to the "Privacy Policy" the purposes, methods, and scope of this SDK's collection and use of personal information, and display the name of this SDK's developer/operator and a link to its privacy policy. On the APP's login/registration page and when the APP is run for the first time, you should inform users of the "Privacy Policy" in concise, prominent, and easily accessible ways such as pop-ups, text links, and attachments, in clear and understandable language, so that users can make a voluntary and explicit expression of intent on the premise of full knowledge.
We provide the following sample notice text for your reference; you may inform users through text or tables. Please understand that the functional services provided by different SDK versions and the required field information may differ due to developers' choices or configurations, so please refer to the SDK privacy policy and the actual SDK integration and operation of the version you use to fully inform users and obtain their consent.
Android Reference Example
- Third-party SDK name: WorkBuddy Share SDK
- Company name of the third-party SDK provider: Tencent Cloud Computing (Beijing) Co., Ltd.
- Purpose and functional scenario: WorkBuddy Open SDK is a software development kit that provides apps developed and operated by developers with capabilities such as sharing content to WorkBuddy
- Types of personal information processed: app package name, app signing certificate fingerprint, content actively selected by the user for sharing (text, link, image, file, and its file name, type, size, and checksum), share metadata (title, description, thumbnail, optional), and signature information (generated by the developer's server)
- Permissions required to implement the SDK's product functions: None
- Third-party SDK privacy policy link: The privacy policy published on the WorkBuddy official website (https://open.workbuddy.cn/)
- Third-party SDK official website link (optional disclosure): https://open.workbuddy.cn/
- Processing method (optional disclosure): Processed locally on the device, securely handed over between apps, not uploaded to servers
iOS Reference Example
- Third-party SDK name: WorkBuddy Share SDK
- Company name of the third-party SDK provider: Tencent Cloud Computing (Beijing) Co., Ltd.
- Purpose and functional scenario: WorkBuddy Share SDK is a software development kit that provides apps developed and operated by developers with capabilities such as sharing content to WorkBuddy
- Types of personal information processed: app Bundle ID, content actively selected by the user for sharing (text, link, image, file, and its file name, type, size, and checksum), share metadata (title, description, thumbnail, optional), and signature information (generated by the developer's server)
- Permissions required to implement the SDK's product functions: Calls the clipboard permission to implement data transfer between third-party apps and WorkBuddy
- Third-party SDK privacy policy link: The privacy policy published on the WorkBuddy official website (https://open.workbuddy.cn/)
- Third-party SDK official website link (optional disclosure): https://open.workbuddy.cn/
- Processing method (optional disclosure): Processed locally on the device, securely handed over between apps, not uploaded to servers
HarmonyOS Reference Example
- Third-party SDK name: WorkBuddy Share SDK
- Company name of the third-party SDK provider: Tencent Cloud Computing (Beijing) Co., Ltd.
- Purpose and functional scenario: WorkBuddy Share SDK is a software development kit that provides apps developed and operated by developers with capabilities such as sharing content to WorkBuddy
- Types of personal information processed: app Bundle Name, app identifier (appIdentifier), app signing certificate fingerprint, content and metadata actively selected by the user for sharing, and signature information (generated by the developer's server)
- Permissions required to implement the SDK's product functions: None
- Third-party SDK privacy policy link: The privacy policy published on the WorkBuddy official website (https://open.workbuddy.cn/)
- Third-party SDK official website link (optional disclosure): https://open.workbuddy.cn/
- Processing method (optional disclosure): Processed locally on the device, securely handed over between apps, not uploaded to servers
III. Initialize the SDK Only After Obtaining User Consent
To meet the requirements of laws, regulations, and regulators, you should ensure that the SDK is initialized only after obtaining the user's consent, and that the call to send a request is completed by configuring the relevant SDK parameters only after the user triggers a specific SDK functional service; only then will the SDK collect the personal information required by the function or request the permissions required by the function according to the configuration you set. To avoid starting the SDK to collect and use users' personal information before you obtain user consent, the SDK provides API interfaces for delayed SDK initialization and compliant initialization technical configuration schemes. Click here to view the detailed operation guide.
- Android Integration Guide and Developer Guide
- iOS Integration Guide and Developer Guide
- HarmonyOS Integration Guide and Developer Guide
- Ensure that after the user has read the APP privacy policy and granted authorization, you call the
registerinterface to initialize the SDK at an appropriate time according to the APP's functional needs. Conversely, if the user does not agree to the "Privacy Policy" authorization, the initialization interface must not be called. This interface only performs initialization and does not obtain personal information. - Do not dynamically request sensitive device permissions involving users' personal information before the user agrees to the privacy policy; do not privately collect and report personal information before the user agrees to the privacy policy (pay particular attention to information such as Android_ID, OAID, IMEI, MAC address, hardware serial number, and app installation list). Do not request SDK-related services when the APP is in an inactive state (for example, when the APP is running in the background).
IV. Optional Information Configuration Switches
1. Configure optional permissions
Please note that this SDK calls the clipboard permission only when sharing content on iOS, for information transfer between third-party apps and WorkBuddy, and does not request other system permissions. Click here to view the detailed operation guide.
| Operating system | Permission name | Purpose | Timing of invocation |
|---|---|---|---|
| iOS | Clipboard permission | Implements information transfer between third-party apps and WorkBuddy on iOS, writing and reading relevant information in the clipboard | When the user actively triggers sharing and launches WorkBuddy |
2. Configure optional personal information
Please note that this SDK does not forcibly obtain optional parameters; even without optional parameters, the basic functions provided by the SDK work normally. The optional personal information involved in this SDK is share metadata (title, description, thumbnail) and signature information: shared content and metadata are both passed in only after the user actively selects them in your app; if metadata is not passed, the SDK does not process the title, description, or thumbnail; if signature is not passed, the SDK does not process signature information; if checkAppInstallation is not called, the SDK does not query the WorkBuddy installation status. Click here to view the detailed operation guide.
3. Configure personal information collection at different frequencies and precisions
(1)The SDK's data collection is triggered only when the APP makes a call and the end user triggers the relevant function; it does not involve frequency control options such as timed logic.
(2)This SDK does not involve location-related functions and does not request precise or approximate geographic location permissions.
4. Guidance and recommendations
Please pay particular attention that when installing, running, and using related functions of the APP, you should comply with the requirements of relevant national laws, regulations, regulatory policies, and standards, and the collection of users' personal information or requests for sensitive permissions must not involve the following violations:
(1)Do not collect any personal information without user consent.
(2)Where it is not necessary for the service or there is no reasonable application scenario, the app must not automatically exit or close after the user refuses the relevant authorization request.
(3)After the user explicitly refuses a permission request, the APP should not frequently show pop-ups or repeatedly request permissions unrelated to the current service scenario in a way that affects normal use; it is recommended to request sensitive permissions at an appropriate time without affecting the availability of other functions.
(4)Do not fail to clearly inform users of the purpose and use of the requested permissions.
(5)When the APP is opened for the first time or while running, if the relevant function or service corresponding to a permission has not been used, do not show pop-ups in advance requesting that sensitive permission be enabled.
(6)Do not excessively collect personal information beyond what is actually needed by business functions.
V. SDK Extended Business Function Configuration
This SDK provides the following interface configurations; it is recommended that you configure and use them according to actual needs.
1. Auto-start declaration
This SDK has no auto-start or associated-start capability, does not start any process when the developer's app is not open, and involves no auto-start declaration.
2. Declaration of launching other apps
(1)When you use this SDK's sharing capability in your app, the SDK launches the WorkBuddy client or opens the system app store page when the user actively triggers sharing or taps "Go to Install". You need to inform end users in the "Privacy Policy", obtain end users' consent, and provide end users with a setting to disable this feature.
(2)We have provided you with the share and openAppStore interfaces and a way to remove this capability: do not call the above interfaces, or call them only when the share entry is tapped, to disable the ability to launch other apps. Click here to view the detailed operation guide.
All three platforms need to declare WorkBuddy's visibility and jump schemes in the host project; this configuration is not a system permission and does not trigger a permission pop-up. Capability identifiers may expand as new capabilities are added; refer to the latest Developer Guide for details.
| Platform | Configuration item | Purpose |
|---|---|---|
| Android | The <queries> merged by the AAR declares com.tencent.workbuddy.app; a read-only FileProvider | Determine whether WorkBuddy is visible and grant WorkBuddy one-time read-only file access. No storage permission and no QUERY_ALL_PACKAGES required |
| iOS | LSApplicationQueriesSchemes in Info.plist declares workbuddy and workbuddy-opensdk | Determine whether WorkBuddy is installed and launch WorkBuddy to complete sharing |
| HarmonyOS | querySchemes declares workbuddy | Determine whether WorkBuddy is installed and launch WorkBuddy to complete sharing |
Installation detection description: checkAppInstallation only queries the installation status of the WorkBuddy client visible to the current user, does not read versions, protocols, or usage records, and does not cache results; returning NOT_DETECTED may result from system visibility restrictions and cannot be used to confirm that the app is uninstalled. The installation detection result does not mean sharing capability is available, nor that content has been delivered.
Share capability verification: before calling share, the SDK verifies whether the WorkBuddy client has sharing capability. On Android, it parses the receiving component of the sharing capability identifier (scheme) registered by WorkBuddy and verifies the protocol version, then reads the client version number and compares it with the minimum supported version; on iOS and HarmonyOS, it determines capability by detecting whether that sharing capability identifier can be opened. If not available, it returns unsupported or unavailable. Capability identifiers are adjusted as new capabilities are added; refer to the latest Developer Guide for details.
VI. Contact Information
If you need our assistance in fulfilling other personal information subject rights requests of your end users, you can apply for assistance through "Contact Information". We have set up a dedicated personal information protection team and a personal information protection officer. If you and/or end users have any questions, complaints, or suggestions about these Rules or personal information protection matters, you can contact us through the following methods:
(i) Contact us through Tencent Customer Service (https://kf.qq.com/);
(ii) Send questions to Dataprivacy@tencent.com;
(iii) Mail a letter to: Data Privacy Protection Department, Tencent Binhai Building, No. 33 Haitian 2nd Road, Nanshan District, Shenzhen, Guangdong Province, China, Postal Code: 518054.
We will review the issues involved as soon as possible and provide feedback within 15 working days or within the period stipulated by laws and regulations.
VII. Notes
1. Compliance self-check before integrating this SDK
To ensure that you have obtained end users' authorization for the use of this SDK and comply with personal information protection requirements and compliance processes, we recommend that you perform a compliance self-check before integrating this SDK.
-
Carefully read and follow the prompts in this guide to perform a compliance self-check of your APP's "Privacy Policy", and confirm that the SDK name, provider, purpose, information types, and privacy policy link have been disclosed.
-
Be sure to configure delayed initialization to ensure
registeris called only after obtaining user consent, without registering or sharing in advance during the app startup phase. -
Call
shareonly when the user actively triggers sharing, not in the background, in scheduled tasks, or in an inactive state. -
Complete the visibility and jump declaration configuration for all three platforms as described in Section IV, without requesting additional permissions unrelated to this SDK.
-
When this SDK is updated based on the latest laws, regulations, or regulatory requirements, promptly upgrade to the latest version upon receiving a version update notification.
-
Comply with other relevant national laws, regulations, regulatory policies, and standards.
2. Our compliance review of you
You should comply with laws, regulations, regulatory policies, and standards related to personal information protection and ensure compliant use of this SDK's services. To ensure that you have actually obtained end users' authorization and have met the relevant compliance requirements for personal information protection, we may, as appropriate, conduct necessary personal information protection compliance reviews of you before or during the conclusion of an agreement or the course of cooperation. During such compliance reviews, you should provide necessary cooperation, including but not limited to:
-
Requesting that you provide proof of the lawful source of the shared personal information and related documents;
-
Reviewing the privacy policy texts available on your official website and other public channels;
-
Trying out your APP to review the consent and authorization notification mechanism and other compliance mechanisms.
If we find non-compliance, you may be required to add or supplement relevant compliance measures; if you fail to do so on time, we have the right to refuse your use of this SDK. Please note that such compliance reviews are only our internal necessary compliance procedures and do not constitute any form of commitment or guarantee, nor do they have legal effect.
3. The following compliance documents are for developers' reference
(1)Personal Information Protection Law of the People's Republic of China
(9)GB/T 35273-2020 Information Security Technology — Personal Information Security Specification
WorkBuddy Share SDK Personal Information Protection Rules
Update date: 2026-10-31
Effective date: 2026-10-31
Introduction
The WorkBuddy Share SDK (hereinafter "SDK Product") is developed by Tencent Cloud Computing (Beijing) Co., Ltd. (hereinafter "we"), whose place of registration is Beijing.
The "WorkBuddy Share SDK Personal Information Protection Rules" (hereinafter "these Rules") mainly inform developers and their end users ("end users") of how the SDK Product needs to collect, use, and process end users' personal information in order to implement the relevant functions of the SDK Product.
Please read these Rules carefully. If you are a developer, please confirm that you fully understand and agree to these Rules before integrating the SDK Product; if you do not agree to these Rules and to performing the corresponding user personal information protection obligations under these Rules, you should immediately stop integrating and using the SDK Product.
Special Notes:
If you are a developer, you should:
1. Comply with laws and regulations when collecting, using, and processing end users' personal information, including but not limited to formulating and publishing a privacy policy on personal information protection;
2. Inform end users of how the SDK Product collects, uses, and processes end users' personal information, obtain end users' consent in accordance with the law, and initialize the SDK Product after obtaining end users' consent;
3. Before obtaining end users' consent and before users trigger the corresponding functional scenarios, unless otherwise provided by laws and regulations, do not collect any end users' personal information;
-
According to the specific functional scenarios of your app, call the corresponding SDK functions, invoke the corresponding permissions, or process end users' personal information when users trigger specific functional scenarios; do not call the corresponding SDK functions, invoke the corresponding permissions, or process end users' personal information before the specific functional scenario is reached;
-
Provide end users with an easy-to-operate mechanism for exercising user rights that meets legal requirements, and inform end users how to access, copy, modify, and delete personal information, withdraw consent, restrict personal information processing, transfer personal information, obtain copies of personal information, and cancel accounts;
-
Comply with the requirements of these Rules and read the "SDK Compliance Usage Guide" carefully for detailed operation instructions.
If developers and end users have any questions or suggestions about the content of these Rules, they can contact us at any time through the methods provided in Section VIII of these Rules.
I. Information We Collect and How We Use It
(1) Personal information collected to implement the SDK Product's functions
As necessary to implement the basic business functions of the SDK Product, we will collect from end users or developers the following personal information generated when end users use functions related to the SDK Product. The SDK also provides optional extended business functions (installation detection, launching other apps), which developers can call as needed; see the "SDK Compliance Usage Guide" for configuration methods. If other extended business functions are provided later, they will be explained through this privacy policy, and configuration methods and examples will be provided to developers through the "SDK Compliance Usage Guide".
| Personal information type | Purpose and functional scenario | Processing method |
|---|---|---|
| App identity information: app package name (Android), Bundle ID (iOS), Bundle Name and app identifier appIdentifier (HarmonyOS), and the SHA-256 fingerprint of the app signing certificate (required, basic business function) | When the developer calls register, confirm the caller's identity for comparison with the sharing app information registered on the server, preventing other apps from impersonating it | Processed locally on the device, securely handed over between apps, not uploaded to servers |
| Shared content: text, link URL, image, and file actively selected by the user, including file name, MIME type, byte count, and SHA-256 checksum (required, basic business function) | Deliver the content selected by the user to the WorkBuddy client and pre-fill it into the conversation box | Processed locally on the device, securely handed over between apps, not uploaded to servers |
| Share metadata: title, description, thumbnail (optional, basic business function) | Display the title and preview of the shared content in the WorkBuddy conversation box | Processed locally on the device, securely handed over between apps, not uploaded to servers |
| Signature information: key identifier kid, message digest message, random number nonce, timestamp timestamp, signature value sig (optional, basic business function) | For the WorkBuddy client to verify the source and integrity of this share request | Processed locally on the device, securely handed over between apps, not uploaded to servers |
| Request identifier requestId (required, basic business function) | Correlate this share request with the returned result to help locate the cause of failure | Processed locally on the device, securely handed over between apps, not uploaded to servers |
| WorkBuddy client installation status: whether installed (optional, extended business function) | Determine whether sharing can be completed; the installation detection result does not mean sharing capability is available, nor that content has been delivered | Processed locally on the device, securely handed over between apps, not uploaded to servers |
| Whether the WorkBuddy client's sharing capability identifier is available, and on Android also reading the client version number (required, basic business function) | Determine whether the client has sharing capability and whether the version meets the minimum requirement, returning unsupported if not | Processed locally on the device, securely handed over between apps, not uploaded to servers |
This SDK does not process sensitive personal information.
The optional personal information involved in this SDK is share metadata (title, description, thumbnail) and signature information: if the developer does not pass metadata, the SDK does not process the title, description, or thumbnail; if the developer does not pass signature, the SDK does not process signature information. The optional extended business functions are installation detection and launching other apps: if the developer does not call checkAppInstallation, the SDK does not query the WorkBuddy client installation status; if the developer does not call share or openAppStore, the SDK does not launch other apps. See the "SDK Compliance Usage Guide" for specific configuration methods.
If a user uses iOS, in order to implement the information transfer between third-party apps and WorkBuddy involved in the aforementioned functions on iOS, we need to call the iOS clipboard permission and write and read the above relevant information in the clipboard. Apart from this, this SDK does not request other system permissions.
(2) According to laws and regulations, the following are exceptions where user consent is not required:
1. Necessary for concluding or performing a contract with the end user;
2. Necessary for performing our statutory obligations;
3. Necessary for responding to a public health emergency, or for protecting end users' life, health, and property safety in an emergency;
4. Processing end users' personal information within a reasonable scope for news reporting, public opinion supervision, and other acts carried out for the public interest;
5. Processing personal information disclosed by end users themselves or otherwise lawfully disclosed within a reasonable scope in accordance with this Law;
6. Other circumstances provided by laws and administrative regulations.
Special note: if the information we collect cannot identify an end user's personal identity either alone or in combination with other information, it does not constitute personal information in the legal sense.
II. Third-Party Data Processing and Public Disclosure of Information
We will not share end users' personal information with our affiliates, partners, or third parties ("recipients").
We will not transfer end users' personal information to other companies, organizations, or individuals, except in the following cases:
-
We inform end users in advance of the types, purpose, method, and scope of the personal information to be transferred and obtain their separate consent;
-
Where personal information needs to be transferred due to merger, division, dissolution, being declared bankrupt, or other reasons, we will inform end users of the recipient's name or personal name and contact information and require the recipient to continue fulfilling the obligations of a personal information processor. If the recipient changes the original processing purpose or method, we will require the recipient to obtain end users' consent again.
We will not publicly disclose end users' personal information, except in the following cases:
-
After informing end users of the types, purpose, method, and scope of the personal information to be publicly disclosed and obtaining their separate consent;
-
Where required by laws and regulations, legal procedures, litigation, or mandatory requirements of competent government authorities.
III. How End Users Manage Their Own Information
We attach great importance to end users' rights to manage their personal information and strive to help end users manage personal information, including accessing, copying, deleting, and canceling accounts, as well as setting privacy functions, in order to safeguard end users' rights.
If you are a developer, you should provide end users with ways to access, copy, modify, and delete personal information, withdraw consent, and cancel accounts.
Developers can contact us through the methods provided in Section VIII of these Rules so that developers can help end users manage their own information.
If you are an end user, since we have no direct interactive dialogue interface with you, you can contact the developer directly to manage your personal information, or contact us through the methods provided in Section VIII of these Rules. Please understand that specific business functions or services require the information needed for the service to be completed; after you withdraw consent, we cannot continue to provide you with the corresponding function or service and will no longer process your corresponding personal information. Your decision to withdraw consent does not affect our prior processing of personal information based on your authorization.
IV. Storage of Information
(1) Where information is stored
We comply with laws and regulations and store personal information collected and generated within the territory of the People's Republic of China within that territory.
(2) Retention period of information
Generally, we retain end users' personal information only for the shortest time necessary to achieve the purpose, except in the following cases:
· To comply with applicable laws, regulations, and other relevant provisions;
· To comply with court judgments, rulings, or other legal procedures;
· To comply with law enforcement requirements of relevant government authorities.
V. Information Security
We provide corresponding security safeguards for end users' personal information to prevent loss, improper use, unauthorized access, or disclosure of information.
We strictly comply with laws and regulations to protect end users' personal information.
We will use various security protection measures within a reasonable level of security to safeguard information security. For example, we use encryption technology, anonymization, and other means to protect end users' personal information.
We have established rigorous management systems, processes, and organizations to ensure information security. For example, we strictly limit the scope of personnel who can access information, require them to observe confidentiality obligations, and conduct reviews.
If a security incident such as a personal information leak occurs, we will activate the emergency plan, stop the incident from escalating, and notify developers through push notifications, announcements, and other forms.
VI. Protection of Minors
This SDK Product is mainly intended for adults.
If you are a developer and an end user is a minor under the age of 14 ("child"), you should inform the child's parents or other guardians of these Rules and process the child's personal information only after obtaining the consent of the child's parents or other guardians. If we discover that a developer has provided us with a child's personal information without obtaining the consent of the child's guardian, we will take measures to delete it as soon as possible.
If you are a child's guardian, when you have questions or rights requests regarding the protection of the child's personal information under your guardianship, you can contact the developer or contact us through the methods provided in Section VIII of these Rules.
VII. Changes
We will revise the content of these Rules from time to time.
If a revision of these Rules would materially diminish end users' rights under these Rules, we will notify you through website announcements and other means before the change takes effect. If you are a developer, when the updated Rules change the handling of end users' personal information, you should update your privacy policy in due course and notify end users in a pop-up and obtain their consent; if an end user does not agree to accept these Rules, please stop integrating the SDK Product.
VIII. Contact Us
We have set up a dedicated personal information protection team and a personal information protection officer. If developers and/or end users have any questions, complaints, or suggestions about these Rules or personal information protection matters, you can contact us through the following methods: (i) Contact us through https://kf.qq.com/; (ii) Send questions to Dataprivacy@tencent.com; (iii) Mail a letter to: Data Privacy Protection Department, Tencent Binhai Building, No. 33 Haitian 2nd Road, Nanshan District, Shenzhen, Guangdong Province, China, Postal Code: 518054. We will review the issues involved as soon as possible and provide feedback within 15 working days or within the period stipulated by laws and regulations.
