Skip to content

Commit aac348a

Browse files
BloominggBloomingg
committed
docs(uniapp): align English calling guides with Wasm
1 parent f67e4a5 commit aac348a

12 files changed

Lines changed: 313 additions & 38 deletions

File tree

‎content/docs/chat/sdk/uniapp/calling/managing-calls/accept-call.mdx‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,22 @@ sourcePath: '/sdk/uniapp/calling/managing-calls/accept-call'
1414
```uts
1515
import { signalingAccept } from '@/uni_modules/unix-openim-sdk'
1616
17-
const result = await signalingAccept({ invitation })
17+
const roomCredentials = await signalingAccept({ invitation })
1818
```
1919

20-
This is <span className="enterprise-field-badge">Commercial</span>. Validate the session and obtain microphone/camera permission before sending accept. Keep optional token/room/live URL only in memory. Promise completion, remote events, and media connection are separate phases.
20+
`signalingAccept()` is <span className="enterprise-field-badge">Commercial</span>. Pass the original `OpenIMSignalingInvitationInfo` received from `onReceiveNewInvitation`; it must retain the room, inviter, invitees, and session type. Do not reconstruct it.
21+
22+
Validate the active SDK session and request microphone or camera permission before accepting. If permission is denied, do not send an accept request; reject the call or explain the failure according to the product flow.
23+
24+
## Result
25+
26+
The Promise resolves to `OpenIMSignalingAcceptResult | null`:
27+
28+
| Field | Type | Description |
29+
| --- | --- | --- |
30+
| `roomID` | `string` or `null` | Media room identifier for this call. |
31+
| `token` | `string` or `null` | Short-lived credential used to join the room. |
32+
| `liveURL` | `string` or `null` | Media service connection address. |
33+
| `invitation` | `OpenIMSignalingInvitationInfo` or `null` | Invitation snapshot returned by the server. |
34+
35+
Keep these values only in memory. Join the media engine only after obtaining a valid `roomID` and `token`. Promise completion, remote signaling events, and an established media connection are separate phases; continue merging state through [call events](/sdk/uniapp/calling/managing-calls/handle-call-events).

‎content/docs/chat/sdk/uniapp/calling/managing-calls/cancel-call.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,8 @@ import { signalingCancel } from '@/uni_modules/unix-openim-sdk'
1717
await signalingCancel({ invitation })
1818
```
1919

20-
This <span className="enterprise-field-badge">Commercial</span> operation is for a caller before connection; hangup is for an accepted/connecting session. Prevent duplicate actions and resolve cancel/accept races from events.
20+
`signalingCancel()` is <span className="enterprise-field-badge">Commercial</span> and is called by the inviter while the invitation is still unanswered. Pass the complete original `OpenIMSignalingInvitationInfo`; a newly constructed object containing only `roomID` is not sufficient.
21+
22+
Cancellation and hangup have different meanings: cancel an unanswered invitation, and hang up an accepted or connecting session.
23+
24+
Promise success means the cancel signaling request completed. The app must also leave its local waiting state and release media resources that were prepared but not used. The remote side updates through `onInvitationCancelled`. Prevent duplicate actions and resolve cancel/accept races from [call events](/sdk/uniapp/calling/managing-calls/handle-call-events).

‎content/docs/chat/sdk/uniapp/calling/managing-calls/handle-call-events.mdx‎

Lines changed: 50 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -11,23 +11,64 @@ platform: 'uniapp'
1111
sourcePath: '/sdk/uniapp/calling/managing-calls/handle-call-events'
1212
---
1313

14-
All <span className="enterprise-field-badge">Commercial</span> call events deliver raw JSON strings. Acknowledge quickly, validate JSON, then map to your own call domain model.
14+
Keep <span className="enterprise-field-badge">Commercial</span> call listeners in one call-state layer. Merge invitation lifecycle, participant connection, and stream changes into the same local state keyed by `roomID`. Every event delivers a raw JSON string; keep the callback short, validate JSON, and then map it to the application's call domain model.
15+
16+
| Event | Purpose |
17+
| --- | --- |
18+
| `onReceiveNewInvitation` | A new call invitation arrived. |
19+
| `onInviteeAccepted`, `onInviteeRejected` | The current invitation was accepted or rejected. |
20+
| `onInvitationCancelled`, `onInvitationTimeout` | The invitation was cancelled or timed out. |
21+
| `onInviteeAcceptedByOtherDevice`, `onInviteeRejectedByOtherDevice` | Another device for the same account handled it. |
22+
| `onHangUp` | A participant ended the call. |
23+
| `onRoomParticipantConnected`, `onRoomParticipantDisconnected` | Room participant connection changed. |
24+
| `onStreamChange` | Participant media stream state changed. |
1525

1626
```uts
17-
import { off, onHangUp, onInvitationCancelled, onInvitationTimeout, onInviteeAccepted, onInviteeRejected, onReceiveNewInvitation } from '@/uni_modules/unix-openim-sdk'
27+
import {
28+
off,
29+
onHangUp,
30+
onInvitationCancelled,
31+
onInvitationTimeout,
32+
onInviteeAccepted,
33+
onInviteeAcceptedByOtherDevice,
34+
onInviteeRejected,
35+
onInviteeRejectedByOtherDevice,
36+
onReceiveNewInvitation,
37+
onRoomParticipantConnected,
38+
onRoomParticipantDisconnected,
39+
onStreamChange,
40+
type OpenIMSDKEventSubscription,
41+
} from '@/uni_modules/unix-openim-sdk'
1842
1943
function handleCallPayload(payload : string) {
2044
try {
2145
const value = JSON.parseObject<UTSJSONObject>(payload)
2246
if (value != null) routeValidatedCallEvent(value)
23-
} catch (_) { console.error('Invalid call event payload') }
47+
} catch (_) {
48+
console.error('Invalid call event payload')
49+
}
2450
}
25-
const subscriptions = [
26-
onReceiveNewInvitation(handleCallPayload), onInviteeAccepted(handleCallPayload),
27-
onInviteeRejected(handleCallPayload), onInvitationCancelled(handleCallPayload),
28-
onInvitationTimeout(handleCallPayload), onHangUp(handleCallPayload),
51+
52+
const invitationSubscription = onReceiveNewInvitation(handleCallPayload)
53+
const subscriptions : Array<OpenIMSDKEventSubscription> = [
54+
invitationSubscription,
55+
onInviteeAccepted(handleCallPayload),
56+
onInviteeAcceptedByOtherDevice(handleCallPayload),
57+
onInviteeRejected(handleCallPayload),
58+
onInviteeRejectedByOtherDevice(handleCallPayload),
59+
onInvitationCancelled(handleCallPayload),
60+
onInvitationTimeout(handleCallPayload),
61+
onHangUp(handleCallPayload),
62+
onRoomParticipantConnected(handleCallPayload),
63+
onRoomParticipantDisconnected(handleCallPayload),
64+
onStreamChange(handleCallPayload),
2965
]
30-
subscriptions.forEach((subscription) => off(subscription))
66+
67+
function removeCallListeners() {
68+
subscriptions.forEach((subscription) => off(subscription))
69+
}
3170
```
3271

33-
Also register the documented other-device and room-participant events. HarmonyOS returns an unsupported subscription for `onStreamChange`. Deduplicate by room/session plus runtime generation, and never log raw payloads or RTC tokens.
72+
This page is the sole complete listener owner for these 11 events. Merge participant state using both room and user IDs; do not rely on event order, display names, or array positions. Deduplicate with the room ID, local session ID, and runtime generation so stale events cannot reopen UI. Call `removeCallListeners()` when the call state layer is destroyed, the user logs out, or the account changes.
73+
74+
HarmonyOS returns a `platform-unsupported` subscription for `onStreamChange` and does not fabricate a stream event. The other signaling events on this page are supported. Never log raw payloads or RTC tokens.

‎content/docs/chat/sdk/uniapp/calling/managing-calls/hang-up-call.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,8 @@ import { signalingHungUp } from '@/uni_modules/unix-openim-sdk'
1717
await signalingHungUp({ invitation })
1818
```
1919

20-
Lock the <span className="enterprise-field-badge">Commercial</span> ending transition so local, remote, and network causes cannot execute it twice. Close media resources and process `onHangUp` idempotently.
20+
After a call has connected, a participant uses the <span className="enterprise-field-badge">Commercial</span> `signalingHungUp()` operation. Pass the complete `OpenIMSignalingInvitationInfo` used by the current call; its `roomID` must match the active media room.
21+
22+
Promise success only means the hangup signaling request completed. The application must also stop local capture, disconnect the media room, and release camera, microphone, and page resources.
23+
24+
Lock the ending transition so local UI actions, remote hangup, timeout, and network errors cannot execute cleanup twice. Cancellation, rejection, timeout, and hangup should converge on one idempotent cleanup flow keyed by `roomID`. Continue handling `onHangUp` as documented in [call events](/sdk/uniapp/calling/managing-calls/handle-call-events).

‎content/docs/chat/sdk/uniapp/calling/managing-calls/reject-call.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,6 @@ import { signalingReject } from '@/uni_modules/unix-openim-sdk'
1717
await signalingReject({ invitation })
1818
```
1919

20-
Use the complete received <span className="enterprise-field-badge">Commercial</span> invitation; do not reconstruct it or alter `roomID`. Close local incoming UI and handle remote/multi-device events idempotently.
20+
When the user declines an incoming call, pass the complete received `OpenIMSignalingInvitationInfo` to the <span className="enterprise-field-badge">Commercial</span> `signalingReject()` operation. Do not reconstruct the invitation or alter its `roomID`.
21+
22+
Promise success only means OpenIMServer completed the reject request. The local incoming-call UI can then close, while the inviter updates through `onInviteeRejected`. Remote and multi-device events may race with the local action and must be handled idempotently. See [call events](/sdk/uniapp/calling/managing-calls/handle-call-events) for the complete lifecycle.

‎content/docs/chat/sdk/uniapp/calling/managing-calls/start-group-call.mdx‎

Lines changed: 45 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,53 @@ platform: 'uniapp'
1111
sourcePath: '/sdk/uniapp/calling/managing-calls/start-group-call'
1212
---
1313

14+
The <span className="enterprise-field-badge">Commercial</span> `signalingInviteInGroup()` operation starts a group call. It invites only the users listed in `inviteeUserIDList`; setting `groupID` does not automatically invite every group member.
15+
16+
## Parameters
17+
18+
| Parameter | Type | Required | Description |
19+
| --- | --- | --- | --- |
20+
| `invitation.inviterUserID` | `string` | Yes | Current user ID. |
21+
| `invitation.inviteeUserIDList` | `string[]` | Yes | Selected members; exclude the inviter. |
22+
| `invitation.groupID` | `string` | Yes | Target group ID. |
23+
| `invitation.roomID` | `string` | Yes | Shared unique room identifier. |
24+
| `invitation.timeout` | `number` | Yes | Invitation timeout in seconds. |
25+
| `invitation.mediaType` | `string` | Yes | `audio` or `video` by application convention. |
26+
| `invitation.sessionType` | `number` | Yes | Use the matching group session constant. |
27+
| `invitation.platformID` | `number` | Yes | Current native platform constant. |
28+
| `invitation.customData` | `string` | No | Application extension data. |
29+
| `invitation.initiateTime` | `number` | No | Invitation start time. The signaling flow normally maintains it, so new calls can omit it. |
30+
| `invitation.busyLineUserIDList` | `string[]` | No | Busy-user list returned by an existing flow. Omit it when starting a new invitation. |
31+
| `offlinePushInfo` | `OpenIMSignalingOfflinePushInfo` | No | Offline push content. |
32+
| `offlinePushInfo.title` | `string` | Conditional | Push title, required when `offlinePushInfo` is provided. |
33+
| `offlinePushInfo.desc` | `string` | Conditional | Push body, required when `offlinePushInfo` is provided. |
34+
| `offlinePushInfo.ex` | `string` | Conditional | Extension string, required when `offlinePushInfo` is provided. Pass an empty string if unused. |
35+
| `offlinePushInfo.iOSPushSound` | `string` | Conditional | iOS push sound, required when `offlinePushInfo` is provided. |
36+
| `offlinePushInfo.iOSBadgeCount` | `boolean` | Conditional | Whether the push updates the iOS badge, required when `offlinePushInfo` is provided. |
37+
1438
```uts
15-
import { signalingInviteInGroup } from '@/uni_modules/unix-openim-sdk'
39+
import {
40+
OpenIMPlatformAndroid,
41+
OpenIMSessionTypeWriteGroup,
42+
signalingInviteInGroup,
43+
} from '@/uni_modules/unix-openim-sdk'
1644
17-
const result = await signalingInviteInGroup({
18-
invitation: { inviterUserID: selfUserID, inviteeUserIDList: selectedUserIDs, groupID, mediaType: 'audio', timeout: 30, sessionType: 2 },
45+
const roomCredentials = await signalingInviteInGroup({
46+
invitation: {
47+
inviterUserID: currentUserID,
48+
inviteeUserIDList: selectedGroupMemberIDs,
49+
customData: JSON.stringify({ source: 'group-call' }),
50+
groupID,
51+
roomID: groupID,
52+
timeout: 30,
53+
mediaType: 'video',
54+
sessionType: OpenIMSessionTypeWriteGroup,
55+
platformID: OpenIMPlatformAndroid,
56+
},
57+
offlinePushInfo,
1958
})
2059
```
2160

22-
This is <span className="enterprise-field-badge">Commercial</span>. Deduplicate targets and verify current membership. Busy users do not determine later accept/reject/timeout outcomes for all other invitees.
61+
This example reuses the group ID as the room ID. If the application generates a different room ID, all participants must use that value. Use `OpenIMPlatformIOS` on iOS. Exclude the current user, blank IDs, and duplicates, and verify that selected users are still group members.
62+
63+
The Promise resolves to `OpenIMSignalingInviteResult | null`; see [Start a one-to-one call](/sdk/uniapp/calling/managing-calls/start-single-call) for all fields. A busy-user list only identifies members who were busy at invite time. It must not cancel invitations for other users, and success does not mean anyone has accepted. Merge later acceptance, rejection, and timeout through [call events](/sdk/uniapp/calling/managing-calls/handle-call-events).

‎content/docs/chat/sdk/uniapp/calling/managing-calls/start-single-call.mdx‎

Lines changed: 57 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,65 @@ platform: 'uniapp'
1111
sourcePath: '/sdk/uniapp/calling/managing-calls/start-single-call'
1212
---
1313

14+
The <span className="enterprise-field-badge">Commercial</span> `signalingInvite()` operation starts a one-to-one audio or video call. `unix-openim-sdk` creates the signaling invitation; the application still joins its media engine with the returned room credentials.
15+
16+
## Parameters
17+
18+
| Parameter | Type | Required | Description |
19+
| --- | --- | --- | --- |
20+
| `invitation` | `OpenIMSignalingInvitationInfo` | Yes | Invitation for this call. |
21+
| `invitation.inviterUserID` | `string` | Yes | Current logged-in user ID. |
22+
| `invitation.inviteeUserIDList` | `string[]` | Yes | Invitees; use one peer for a one-to-one call. |
23+
| `invitation.groupID` | `string` | Yes | Use an empty string for one-to-one calls. |
24+
| `invitation.roomID` | `string` | Yes | Unique room identifier shared by all call state. |
25+
| `invitation.timeout` | `number` | Yes | Invitation timeout in seconds. |
26+
| `invitation.mediaType` | `string` | Yes | Application convention such as `audio` or `video`. |
27+
| `invitation.sessionType` | `number` | Yes | Use `OpenIMSessionTypeSingle`. |
28+
| `invitation.platformID` | `number` | Yes | Current native platform constant. |
29+
| `invitation.customData` | `string` | No | Application extension data. |
30+
| `offlinePushInfo` | `OpenIMSignalingOfflinePushInfo` | No | Offline push title, description, and iOS settings. |
31+
1432
```uts
15-
import { signalingInvite } from '@/uni_modules/unix-openim-sdk'
33+
import {
34+
OpenIMPlatformAndroid,
35+
OpenIMSessionTypeSingle,
36+
signalingInvite,
37+
} from '@/uni_modules/unix-openim-sdk'
1638
17-
const result = await signalingInvite({
18-
invitation: { inviterUserID: selfUserID, inviteeUserIDList: [peerUserID], mediaType: 'video', timeout: 30, sessionType: 1 },
19-
offlinePushInfo: { title: 'Video call', desc: 'Incoming call' },
39+
const roomCredentials = await signalingInvite({
40+
invitation: {
41+
inviterUserID: currentUserID,
42+
inviteeUserIDList: [peerUserID],
43+
customData: JSON.stringify({ source: 'contact-card' }),
44+
groupID: '',
45+
roomID: createBusinessRoomID(),
46+
timeout: 30,
47+
mediaType: 'video',
48+
sessionType: OpenIMSessionTypeSingle,
49+
platformID: OpenIMPlatformAndroid,
50+
},
51+
offlinePushInfo: {
52+
title: 'Video call',
53+
desc: 'You have an incoming video call',
54+
ex: '',
55+
iOSPushSound: 'default',
56+
iOSBadgeCount: true,
57+
},
2058
})
2159
```
2260

23-
This is <span className="enterprise-field-badge">Commercial</span>. Treat `roomID`, `token`, `liveURL`, and busy-user results as optional; cancel an accepted invitation if presentation fails, and never log credentials.
61+
Use `OpenIMPlatformIOS` on iOS. Generate a stable room ID for this call and keep it consistent across participants.
62+
63+
## Result
64+
65+
The Promise resolves to `OpenIMSignalingInviteResult | null`:
66+
67+
| Field | Type | Description |
68+
| --- | --- | --- |
69+
| `roomID` | `string` or `null` | Media room identifier. |
70+
| `token` | `string` or `null` | Short-lived room credential. |
71+
| `liveURL` | `string` or `null` | Media service connection address. |
72+
| `busyLineUserIDList` | `string[]` or `null` | Users who were busy when invited. |
73+
| `invitation` | `OpenIMSignalingInvitationInfo` or `null` | Server invitation snapshot. |
74+
75+
Join the media engine only after obtaining a valid room ID and token. Promise success does not mean the peer accepted; merge later state through [call events](/sdk/uniapp/calling/managing-calls/handle-call-events). If the application cannot present outgoing call UI after the invite succeeds, actively cancel the invitation. Never log room credentials.

0 commit comments

Comments
 (0)