Okay, so a post in two halves… both quite long. (Again, I’m quite happy to split this if you’d like.)
Getting ZAKs working
Firstly, I did get the ZAK working in the end, and I think I know what I was doing wrong and how a few documentation improvements could have avoided it. Basically, I was using the “other” kind of token given by the /users/me/token API request.
I’m sure I won’t be able to find all the parts of documentation that I went through (it’s a bit labyrinthine, and I can understand that - auth in particular is always really hard to document) but:
-
In https://marketplace.zoom.us/docs/sdk/native-sdks/iOS/mastering-zoom-sdk/start-join-meeting/api-user/authentication, it states:
For Zoom_Access_Token(ZAK), you can retrieve them by sending a GET request to https://api.zoom.us/v2/users/{userId}/token."
But that will give the wrong kind of token (without the query parameter). (I’m sure I reached this page at some point despite not using iOS…)
-
The doc at https://marketplace.zoom.us/docs/sdk/native-sdks/auth is slightly better:
To request a User’s ZAK, send a GET request with a userId to /users/{userId]/token and specify type=zak in the body of the request. (If a type is not specified, the default response will be Zoom Token)
This does at least talk about “type=zak”, but:
- It’s a query parameter, not in the body of the request
- The distinction between “Zoom Token” and “Zoom Access Token” is very, very easy to miss when you’re coming in fresh. This is compounded by the next issue.
-
In https://marketplace.zoom.us/docs/api-reference/zoom-api/users/usertoken, the documentation for the token query parameter was what really confused me. It says there are two types:
token: Used for starting meetings with the client SDK. This token expires in 14 days and a new token will be returned after the expiry.zak Used for generating the start meeting URL. The token expiration time is two hours. For API users, the expiration time is 90 days.
Now given that I’m trying to start a meeting with the client SDK, it really sounds like I want “token” here. I’m not “generating a start meeting URL” at all. I think improving this one piece of documentation, as well as highlighting the presence of the query parameter and the fact that there are different kinds of token at all in the summary information on the page, would make a huge difference. (Ideally, define the two kinds of token using terms that are very easily distinguishable. I appreciate that by now it may be too late to do that.)
-
There’s an inconsistency in whether starting a meeting with a ZAK counts as a “login” user or a “non-login user”. Reading https://marketplace.zoom.us/docs/sdk/native-sdks/user-login makes it sound like using OAuth is part of the “login user” or “non-login user” flow… in the API call, we’re using withoutLoginStart and StartParam4WithoutLogin, which certainly sounds like it’s non-login… but this isn’t an anonymous user. Perhaps you need a third category in the description here?
I hope those suggestions are useful.
Personally I would really have preferred it if an incorrect ZAK (or at least a token which was completely invalid as a ZAK in terms of the format) would have caused an error rather than trying to join anonymously. There are plenty of other places where the API reports an error even for cases where it’s harmless - like requesting to show the toolbar when it’s already being shown. In that case, reporting the error is unhelpful, whereas here it would be really helpful for alerting the developer to the fact that their code has a bug. I appreciate it’s probably too late to change that now though.
Marketplace requirements and experience
Firstly, I’m still confused about the production vs testing URLs. I can generate both URLs in the app configuration wizard, but only the “local testing” one works at the moment. (Trying to exchange the code for an OAuth token fails with a 4xx error.) I think I’ve seen it the other way round as well, but I’m not sure. (I was changing too many things to have paid much attention on that.)
The terminology of “installing” and “uninstalling” an application is definitely confusing here. From my standpoint, I’m not installing anything - I’m authenticating or logging in. I assume that “uninstall” really means “invalidate previous token” but that’s unclear too.
Anyway, I’ll assume that this can all be sorted. My bigger concern is being able to create an application with very limited distribution without making it public on the Marketplace. Here’s my bigger context…
I have developed two applications, “Zoom and Enhance” (ZAE) and “At Your Service” (AYS). Both are basically to help me with A/V presentation for my local church, and both are Windows-based (WPF).
Zoom and Enhance (ZAE)
ZAE was started last year, and is effectively a Zoom productivity app. It’s designed for the situation where everyone in a church service is attending via Zoom, and is primarily about streamlining a few bits of functionality which are common within Zoom services - plus a few extras. It can:
- Change the spotlight from one user to another, muting everyone else and unmuting the new speaker, all with a single double-click
- Launch a PowerPoint presentation, video or web page, starting a screen share (either of a screen or the app), again muting everyone else - and again, all with a single double-click. (And importantly, you can prepare the list of videos etc beforehand, so you’re just clicking from one item to the next, via other speakers to spotlight.)
- Unmute everyone (e.g. for saying the Lord’s Prayer) - this is in the normal Zoom client as well of course, but it’s all in the same place as the rest of the functionality for ZAE.
- Automatically rename users as they join (e.g. to turn phone numbers into names)
- Provide crude-but-effective chat-based notification system, so that people can “subscribe” to notifications by chat when someone joins or leaves. That allows a few people to make sure that everyone is greeted as they arrive.
- Make it easy to switch between devices (e.g. different webcams, microphones, speakers) without going through settings menus
While I primarily built ZAE for myself, it now has maybe a dozen users. To avoid issues where the same SDK key was being used at the same time for an unpublished app, each user has registered themselves as a Zoom developer (under the advice of a Zoom engineer last year). I suspect that each user only needs to start meetings for a small handful of “normal” Zoom users (e.g. the account for the minister of that church, or the church council secretary) but it’s not necessarily just their own account.
At Your Service (AYS)
AYS was started this spring, and is a complete replacement for the previous A/V system at my local church. Our “A/V stewards” are just volunteers who are technically literate, but not necessarily geeks, let’s say. I wanted to make things as simple as possible for them, in a world of hybrid worship where some people are on Zoom and some are in the church building. Before the pandemic, the A/V stewards would primarily need to worry about the sound via microphones, and what’s on the screen via a computer. Adding Zoom and cameras into the mix made it infeasible to have lots of separate pieces of hardware and software, so I’ve built a platform myself which controls:
- Sound via a digital mixer
- Presentation of videos/audio/pictures via VLC
- PowerPoint
- Song words and liturgy as text
- Multiple cameras (with control for pan/tilt/zoom)
- Window management for all of the above (e.g. to show singers with the song words overlaid, or a regular video overlaid with a camera shot in the corner)
- Zoom:
- Starting the meeting for people to join
- Spotlighting people who are doing a reading (and then returning to show the church view)
- OBS for recording services
Again, the intention is to allow as much to be done with a single mouse double-click (or button-press on a Stream Deck) as possible.
Currently, the only installations of At Your Service are me for development and on the church computer. Other churches aren’t using it, partly as it’s very much geared towards our hardware.
Most of the meetings started by AYS are with the same account, although that’s a separate account from the one I’ve created the app in. (Church account vs my personal account.)
How OAuth and the Marketplace fits in
So these applications are only ever intended to be distributed by me personally - no-one is going to be able to install them without coming to me first. That’s why it would seem odd to have a Marketplace app that’s publicly visible: “Here’s an application that you can find out about - but you won’t actually be able to use” is odd messaging.
While it’s awkward, I could potentially create a new OAuth app which is never submitted for review, on each account where we host meetings - and ask the handful of ZAE users to do the same thing.
The other alternative is to go via the “Request to share this app outside this account” dialog in the Marketplace app management part. If the Zoom Marketplace Team would consider this an acceptable use case, that would be simpler. I’d need to get the published URL client id/secret to work but I’m sure that’s manageable.
I’m sure once we’ve worked out how many OAuth apps are required (in order to allow hosting from “multiple, but not a huge number” of other accounts), I can do the server-side OAuth management and then app-side ZAK-fetching relatively easily.
If you have any other ideas, I’d be very interested in hearing them. I hope all the above context is useful for the product team in terms of giving background as to how the Zoom SDK is being used in real life outside enterprises etc. (I’m sure enterprise use cases are much more important to the product team, of course - I don’t begrudge Zoom wanting to make money!)
