docs: say "connector token" and "web calling token" throughout - #31
Merged
Conversation
Settles on one name per credential across the docs, examples, and the
SDK's user-facing copy.
- "API key" -> "connector token" in prose. The repo had already started
this migration (README/PolyVoice.md snippets were annotated
"// connector token", and e2e-validation.sh reads POLY_CONNECTOR_TOKEN),
so this finishes it. Uses "connector token" rather than a bare "token"
because a voice call takes two tokens and the docs are trying to tell
them apart.
- "WebRTC token" -> "web calling token", for the credential ONLY. Every
reference to WebRTC-the-protocol or the WebRTC dependency (media,
binary, xcframework, audio engine, WebRTC-lib) is left alone -- those
are factual and renaming them would make correct docs wrong.
- A third name for the same credential ("gateway token") is folded into
"web calling token".
- Placeholders: YOUR_API_KEY -> YOUR_CONNECTOR_TOKEN, YOUR_WEBRTC_TOKEN
-> YOUR_WEB_CALLING_TOKEN, in both the READMEs and the example sources
so they can't drift. scripts/e2e-validation.sh substitutes
YOUR_API_KEY at test time and is updated to match -- without that, e2e
would have built the examples with an unsubstituted placeholder.
- User-facing SDK copy that contradicted the new docs: PolyError's
"Your API key was rejected", SessionState's "Invalid API key", and the
initialize() fatalError hint.
No public API symbols were renamed. Configuration.apiKey and
VoiceOptions.webrtcToken are untouched, so this is not a breaking change
and every snippet still compiles -- 72b54a9 settled that surface for
0.9.0 and this does not reopen it. The tradeoff is that prose now says
"connector token" next to a symbol still called apiKey; renaming the
symbols would be a separate, breaking PR.
swift build clean; 283 tests pass.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Picks one name per credential across docs, examples, and the SDK's user-facing copy.
What changed
YOUR_API_KEYYOUR_CONNECTOR_TOKENYOUR_WEBRTC_TOKENYOUR_WEB_CALLING_TOKENTwo deliberate limits
No public API symbols were renamed.
Configuration.apiKeyandVoiceOptions.webrtcTokenare byte-identical, so this is not a breaking change and every snippet still compiles. 72b54a9 settled that surface for 0.9.0 and this doesn't reopen it.The tradeoff worth reviewing: prose now reads "connector token" next to a symbol still called
apiKey. Renaming the symbols would be a separate, breaking PR — flagging it rather than deciding it here."WebRTC" the protocol is untouched. Only the credential was renamed. "WebRTC media", "the WebRTC binary", the xcframework,
WebRTC-lib, "WebRTC audio engine" all stay — those are factual, and renaming them would turn correct docs into wrong ones.Why "connector token" and not just "token"
A voice call takes two tokens, and the docs exist largely to tell them apart — a bare "token" would be ambiguous exactly where clarity matters most. This also isn't a new coinage:
README.mdanddocs/PolyVoice.mdalready annotated their snippets// connector token, andscripts/e2e-validation.shalready readsPOLY_CONNECTOR_TOKEN. This finishes a migration that was already half-done.One thing that would have broken silently
scripts/e2e-validation.shsubstitutesYOUR_API_KEYinto the example apps at test time. Renaming the placeholder without updating the script would have left an unsubstituted placeholder in the built examples and failed authentication at runtime — updated in the same commit.Placeholders are changed in both the READMEs and the example
.swiftsources, since the READMEs saycurrently "YOUR_..."and would otherwise drift.Also swept
User-facing SDK copy that would have contradicted the new docs:
PolyError.swift— "Your API key was rejected" → "Your connector token was rejected"SessionState.swift— "Invalid API key" → "Invalid connector token"PolyMessaging.swift— theinitialize()fatalErrorhint///doc comments acrossSources/(these render into DocC)PolyErrorDescriptionTests.swiftthat pinned the old wordingVerification
swift buildcleanSources/is one of the user-facing strings listed above — audited via diffYOUR_API_KEY/YOUR_WEBRTC_TOKEN; zero accidentalconnectorToken:/webCallingToken:symbol renamesFollow-up left open
VoiceOptions.swiftdocuments a "WebRTC gateway host" — a host, not a credential, so it was left under the protocol rule. It now sits near "web calling token" and reads slightly inconsistently. Worth a naming decision, not made here.