Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Teams mobile doc improvements #2154

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Teams mobile doc improvements #2154

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
950edcb
Doc updates for Teams mobile clarifications.
JoshuaPartlow Feb 1, 2024
16da13a
Change files
JoshuaPartlow Feb 1, 2024
53e78bf
Corrected locale specific doc link.
JoshuaPartlow Feb 1, 2024
ab1c6ff
Merge branch 'main' into teams-mobile-doc-improvements
AE-MS Feb 1, 2024
e07f063
Update @microsoft-teams-js-795fcb3d-57f7-436b-b7e2-b3d3c2df6bad.json
AE-MS Feb 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
7 changes: 7 additions & 0 deletions change/@microsoft-teams-js-795fcb3d-57f7-436b-b7e2-b3d3c2df6bad.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"type": "patch",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be type "none" since the docs only changes won't affect the behavior of the library at all.

"comment": "Clarified mobile usage in documentation for `app`, `barCode`, `media`, `meeting`, and `teamsAPIs` capabilities.",
"packageName": "@microsoft/teams-js",
"email": "joshuapa@microsoft.com",
"dependentChangeType": "patch"
}
4 changes: 4 additions & 0 deletions packages/teams-js/src/public/app.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -814,6 +814,10 @@ export namespace app {

/**
* Notifies the frame that app has loaded and to hide the loading indicator if one is shown.
*
* @remarks
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@remarks

Should these remarks be specifically on the notifyAppLoaded method like this? It seems like the documentation is generally about how loading indicator is handled and not specific to this one function.

* For information about mobile behavior, see the [Content pages](https://learn.microsoft.com/microsoftteams/platform/tabs/how-to/create-tab-pages/content-page?tabs=teamsjs-v2#show-a-native-loading-indicator) article.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For information about mobile behavior

What should we expect developers to see when they go to that URL? Here is where I think I would be confused: is that page telling me that... I shouldn't call methods like notifyAppLoaded() when I'm on mobile?

I think the answer is "No, your app should always call these methods and you don't need to write special code, but just know that the loading indicator behavior may be different on mobile." Is that correct? If so it's not totally clear from these comments or that doc page.

*
*/
export function notifyAppLoaded(): void {
ensureInitializeCalled();
Expand Down
14 changes: 12 additions & 2 deletions packages/teams-js/src/public/barCode.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,12 @@ export namespace barCode {
/**
* Checks whether or not media has user permission
*
* @returns true if the user has granted the app permission to media information, false otherwise
* @remarks
* For additional information about deivce permissions, see the Learn articles:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be more appropriate if this documentation was on the barCode namespace rather than each function in it? Since the documentation is an overview of the functionality and not specific to each function?

* - [Integrate QR or barcode scanner capability](https://learn.microsoft.com/microsoftteams/platform/concepts/device-capabilities/qr-barcode-scanner-capability)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Integrate QR or barcode scanner capability

Following this link takes me to a page which provides great information about barcode scanning -- but that page then links to a function in the older (1.x) version of teamsjs and a different capability than this one (it links to media) -- is it weird that this capability and function links to docs that don't mention this function at all?

* - [Request device permissions for your Teams app](https://learn.microsoft.com/microsoftteams/platform/concepts/device-capabilities/native-device-permissions?tabs=mobile%2Cteamsjs-v2%2Cmobile1#specify-permissions)
*
* @returns `true` if the user has granted the app permission to media information, `false` otherwise. The **media** permission refers to both camera and gallery.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The media permission refers to both camera and gallery

Can you say more about what this means? I'm not sure I understand this part. Specifically what does "both camera and gallery" mean here? Does that refer to a permission offered from the OS that the app is running on?

*
* @beta
*/
Expand All @@ -88,7 +93,12 @@ export namespace barCode {
/**
* Requests user permission for media
*
* @returns true if the user has granted the app permission to the media, false otherwise
* @remarks
* For additional information about deivce permissions, see the Learn articles:
* - [Integrate QR or barcode scanner capability](https://learn.microsoft.com/microsoftteams/platform/concepts/device-capabilities/qr-barcode-scanner-capability)
* - [Request device permissions for your Teams app](https://learn.microsoft.com/microsoftteams/platform/concepts/device-capabilities/native-device-permissions?tabs=mobile%2Cteamsjs-v2%2Cmobile1#specify-permissions)
*
* @returns `true` if the user has granted the app permission to the media, `false` otherwise. The **media** permission refers to both camera and gallery.
*
* @beta
*/
Expand Down
3 changes: 3 additions & 0 deletions packages/teams-js/src/public/media.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -756,6 +756,9 @@ export namespace media {
/**
* Select an attachment using camera/gallery
*
* @remarks
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remarks

Would it be more appropriate to put this on the media namespace rather than this one function? Presumably this applies to other functions in this file?

* For additional details about media capabilities, see the [Integrate media capabilities](https://learn.microsoft.com/microsoftteams/platform/concepts/device-capabilities/media-capabilities) article.
*
* @param mediaInputs - The input params to customize the media to be selected
* @param callback - The callback to invoke after fetching the media
*/
Expand Down
56 changes: 28 additions & 28 deletions packages/teams-js/src/public/meeting.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,7 @@ export namespace meeting {
*/
export interface LiveStreamState {
/**
* true when the current meeting is being streamed through RTMP, or false if it is not.
* `true` when the current meeting is being streamed through RTMP, or `false` if it is not.
*/
isStreaming: boolean;

Expand Down Expand Up @@ -191,7 +191,7 @@ export namespace meeting {
export interface IAppContentStageSharingCapabilities {
/**
* indicates whether app has permission to share contents to meeting stage.
* true when your `configurableTabs` or `staticTabs` entry's `context` array includes `meetingStage`.
* `true` when your `configurableTabs` or `staticTabs` entry's `context` array includes `meetingStage`.
*/
doesAppHaveSharePermission: boolean;
}
Expand All @@ -210,7 +210,7 @@ export namespace meeting {
*/
export interface ISpeakingState {
/**
* true when one or more participants in a meeting are speaking, or false if no participants are speaking
* `true` when one or more participants in a meeting are speaking, or `false` if no participants are speaking
*/
isSpeakingDetected: boolean;

Expand Down Expand Up @@ -525,8 +525,8 @@ export namespace meeting {
* This API can only be used in the `sidePanel` and `meetingStage` frame contexts.
*
* @param callback - Callback contains 2 parameters, `error` and `result`.
* `error` can either contain an error of type `SdkError`, in case of an error, or null when fetch is successful.
* `result` will be true when incoming audio is muted and false when incoming audio is unmuted, or null when the request fails.
* `error` can either contain a value of type `SdkError`, in case of an error, or `null` when fetch is successful.
* `result` will be `true` when incoming audio is muted and `false` when incoming audio is unmuted, or `null` when the request fails.
*/
export function getIncomingClientAudioState(callback: errorCallbackFunctionType): void {
if (!callback) {
Expand All @@ -551,8 +551,8 @@ export namespace meeting {
* This API can only be used in the `sidePanel` and `meetingStage` frame contexts.
*
* @param callback - Callback contains 2 parameters, `error` and `result`.
* `error` can either contain an error of type `SdkError`, in case of an error, or null when toggle is successful.
* `result` will be true when incoming audio is muted and false when incoming audio is unmuted, or null when the toggling fails.
* `error` can either contain a value of type `SdkError`, in case of an error, or `null` when toggle is successful.
* `result` will be `true` when incoming audio is muted and `false` when incoming audio is unmuted, or `null` when the toggling fails.
*/
export function toggleIncomingClientAudio(callback: errorCallbackFunctionType): void {
if (!callback) {
Expand All @@ -571,8 +571,8 @@ export namespace meeting {
* Allows an app to get the meeting details for the meeting
*
* @param callback - Callback contains 2 parameters, `error` and `meetingDetailsResponse`.
* `error` can either contain an error of type `SdkError`, in case of an error, or null when get is successful
* `result` can either contain a {@link IMeetingDetailsResponse} value, in case of a successful get or null when the get fails
* `error` can either contain a value of type `SdkError`, in case of an error, or `null` when get is successful
* `result` can either contain a {@link IMeetingDetailsResponse} value, in case of a successful get or `null` when the get fails
*
* @internal
* Limited to Microsoft-internal use
Expand Down Expand Up @@ -602,8 +602,8 @@ export namespace meeting {
* Allows an app to get the authentication token for the anonymous or guest user in the meeting
*
* @param callback - Callback contains 2 parameters, `error` and `authenticationTokenOfAnonymousUser`.
* `error` can either contain an error of type `SdkError`, in case of an error, or null when get is successful
* `authenticationTokenOfAnonymousUser` can either contain a string value, in case of a successful get or null when the get fails
* `error` can either contain a value of type `SdkError`, in case of an error, or `null` when get is successful
* `authenticationTokenOfAnonymousUser` can either contain a string value, in case of a successful get or `null` when the get fails
*
* @internal
* Limited to Microsoft-internal use
Expand Down Expand Up @@ -632,8 +632,8 @@ export namespace meeting {
* Find the app manifest reference at https://aka.ms/teamsAppManifest/meetingExtensionDefinition.
*
* @param callback - Callback contains 2 parameters: `error` and `liveStreamState`.
* `error` can either contain an error of type `SdkError`, in case of an error, or null when the request is successful
* `liveStreamState` can either contain a `LiveStreamState` value, or null when operation fails
* `error` can either contain a value of type `SdkError`, in case of an error, or `null` when the request is successful
* `liveStreamState` can either contain a `LiveStreamState` value, or `null` when operation fails
*/
export function getLiveStreamState(callback: getLiveStreamStateCallbackFunctionType): void {
if (!callback) {
Expand All @@ -659,7 +659,7 @@ export namespace meeting {
* The `meetingExtensionDefinition.supportsStreaming` field in your app manifest must be `true` to use this API.
* Find the app manifest reference at https://aka.ms/teamsAppManifest/meetingExtensionDefinition.
*
* @param callback - completion callback that contains an `error` parameter, which can be of type `SdkError` in case of an error, or null when operation is successful
* @param callback - completion callback that contains an `error` parameter, which can be of type `SdkError` in case of an error, or `null` when operation is successful
* @param streamUrl - the url to the RTMP stream resource
* @param streamKey - the key to the RTMP stream resource
*/
Expand Down Expand Up @@ -689,7 +689,7 @@ export namespace meeting {
* The `meetingExtensionDefinition.supportsStreaming` field in your app manifest must be `true` to use this API.
* Find the app manifest reference at https://aka.ms/teamsAppManifest/meetingExtensionDefinition.
*
* @param callback - completion callback that contains an error parameter, which can be of type `SdkError` in case of an error, or null when operation is successful
* @param callback - completion callback that contains an error parameter, which can be of type `SdkError` in case of an error, or `null` when operation is successful
*/
export function requestStopLiveStreaming(callback: liveStreamErrorCallbackFunctionType): void {
if (!callback) {
Expand Down Expand Up @@ -740,8 +740,8 @@ export namespace meeting {
* Use {@link getAppContentStageSharingState} to determine whether app content is already being shared to the meeting stage.
*
* @param callback - Callback contains 2 parameters, `error` and `result`.
* `error` can either contain an error of type `SdkError`, in case of an error, or null when share is successful
* `result` can either contain a true value, in case of a successful share or null when the share fails
* `error` can either contain a value of type `SdkError`, in case of an error, or `null` when share is successful
* `result` can either contain a `true` value, in case of a successful share or `null` when the share fails
* @param appContentUrl - is the input URL to be shared to the meeting stage.
* the URL origin must be included in your app manifest's `validDomains` field.
* @param shareOptions - is an object that contains additional sharing options. If omitted, the default
Expand Down Expand Up @@ -778,8 +778,8 @@ export namespace meeting {
* Find the app manifest reference at https://aka.ms/teamsAppManifest/authorization.
*
* @param callback - Completion callback contains 2 parameters: `error` and `appContentStageSharingCapabilities`.
* `error` can either contain an error of type `SdkError` (error indication), or null (non-error indication).
* `appContentStageSharingCapabilities` will contain an {@link IAppContentStageSharingCapabilities} object if the request succeeds, or null if it failed.
* `error` can either contain a value of type `SdkError` (error indication), or `null` (non-error indication).
* `appContentStageSharingCapabilities` will contain an {@link IAppContentStageSharingCapabilities} object if the request succeeds, or `null` if it failed.
*/
export function getAppContentStageSharingCapabilities(callback: getAppContentCallbackFunctionType): void {
if (!callback) {
Expand All @@ -799,8 +799,8 @@ export namespace meeting {
* Terminates current stage sharing session in meeting
*
* @param callback - Callback contains 2 parameters, error and result.
* error can either contain an error of type SdkError (error indication), or null (non-error indication)
* result can either contain a true boolean value (successful termination), or null (unsuccessful fetch)
* error can either contain a value of type SdkError (error indication), or `null` (non-error indication)
* result can either contain a `true` boolean value (successful termination), or `null` (unsuccessful fetch)
*/
export function stopSharingAppContentToStage(callback: errorCallbackFunctionType): void {
if (!callback) {
Expand All @@ -825,8 +825,8 @@ export namespace meeting {
* Find the app manifest reference at https://aka.ms/teamsAppManifest/authorization.
*
* @param callback - Callback contains 2 parameters, `error` and `appContentStageSharingState`.
* error can either contain an error of type SdkError (error indication), or null (non-error indication)
* `appContentStageSharingState` can either contain an `IAppContentStageSharingState` object if the request succeeds, or null if it failed
* error can either contain a value of type SdkError (error indication), or `null` (non-error indication)
* `appContentStageSharingState` can either contain an `IAppContentStageSharingState` object if the request succeeds, or `null` if it failed
*/
export function getAppContentStageSharingState(callback: getAppContentStageCallbackFunctionType): void {
if (!callback) {
Expand All @@ -846,7 +846,7 @@ export namespace meeting {
*
* @remarks
* This API returns {@link ISpeakingState}, which will have `isSpeakingDetected` and/or an error object.
* If any participant is speaking, `isSpeakingDetected` will be true, or false if no participants are speaking.
* If any participant is speaking, `isSpeakingDetected` will be `true`, or `false` if no participants are speaking.
* Only one handler can be registered at a time. Subsequent registrations replace existing registrations.
* This API can only be used in the `sidePanel` and `meetingStage` frame contexts.
* For private scheduled meetings, meet now, or calls, include the `OnlineMeetingIncomingAudio.Detect.Chat` RSC permission in your app manifest.
Expand All @@ -869,7 +869,7 @@ export namespace meeting {

/**
* Registers a handler for changes to the selfParticipant's (current user's) raiseHandState. If the selfParticipant raises their hand, isHandRaised
* will be true. By default and if the selfParticipant hand is lowered, isHandRaised will be false. This API will return {@link RaiseHandStateChangedEventData}
* will be `true`. By default and if the selfParticipant hand is lowered, isHandRaised will be `false`. This API will return {@link RaiseHandStateChangedEventData}
* that will have the raiseHandState or an error object. Only one handler can be registered at a time. A subsequent registration
* replaces an existing registration.
*
Expand Down Expand Up @@ -992,19 +992,19 @@ export namespace meeting {
/**
* Have the app handle audio (mic & speaker) and turn off host audio.
*
* When {@link RequestAppAudioHandlingParams.isAppHandlingAudio} is true, the host will switch to audioless mode
* When {@link RequestAppAudioHandlingParams.isAppHandlingAudio} is `true`, the host will switch to audioless mode
* Registers for mic mute status change events, which are events that the app can receive from the host asking the app to
* mute or unmute the microphone.
*
* When {@link RequestAppAudioHandlingParams.isAppHandlingAudio} is false, the host will switch out of audioless mode
* When {@link RequestAppAudioHandlingParams.isAppHandlingAudio} is `false`, the host will switch out of audioless mode
* Unregisters the mic mute status change events so the app will no longer receive these events
*
* @throws Error if {@linkcode app.initialize} has not successfully completed
* @throws Error if {@link RequestAppAudioHandlingParams.micMuteStateChangedCallback} parameter is not defined
*
* @param requestAppAudioHandlingParams - {@link RequestAppAudioHandlingParams} object with values for the audio switchover
* @param callback - Callback with one parameter, the result
* can either be true (the host is now in audioless mode) or false (the host is not in audioless mode)
* can either be `true` (the host is now in audioless mode) or `false` (the host is not in audioless mode)
*
* @hidden
* Hide from docs.
Expand Down
8 changes: 4 additions & 4 deletions packages/teams-js/src/public/teamsAPIs.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,8 @@ export namespace teamsCore {
/**
* Registers a handler to be called when the page has been requested to load.
*
* @remarks Check out [App Caching in Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/app-caching)
* for a more detailed explanation about using this API.
* @remarks Check out [App Caching in Teams](https://learn.microsoft.com/microsoftteams/platform/tabs/how-to/app-caching)
* for a more detailed explanation about using this API, including information about platform support.
*
* @param handler - The handler to invoke when the page is loaded.
*
Expand Down Expand Up @@ -93,8 +93,8 @@ export namespace teamsCore {
/**
* Registers a handler to be called before the page is unloaded.
*
* @remarks Check out [App Caching in Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/app-caching)
* for a more detailed explanation about using this API.
* @remarks Check out [App Caching in Teams](https://learn.microsoft.com/microsoftteams/platform/tabs/how-to/app-caching)
* for a more detailed explanation about using this API, including information about platform support.
*
* @param handler - The handler to invoke before the page is unloaded. If this handler returns true the page should
* invoke the readyToUnload function provided to it once it's ready to be unloaded.
Expand Down