Repository navigation
feat(portal): load custom scripts from portal.scripts #477
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.
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
base: dev
Are you sure you want to change the base?
Changes from all commits
19cb032
2580c4e
bf320b4
7849475
cea1bc0
6782e26
a0c6d99
5f22073
88fe45d
8d11751
6ed31b3
310f38a
d9058be
ddbad82
78505ad
97946a2
bc7ec36
e50ac0a
5f1d49d
07ee1f4
3df7c3d
17ddf35
1547e42
440f0b2
94c5897
be9556c
5ad3cfe
367cf0b
95780b1
37db2b4
9a6e19b
7b49143
a895b2c
eb200e9
a3a04d3
f751809
ae99bcc
37dcd1b
b9450b7
6792fa8
3fc4fdd
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -38,6 +38,11 @@ | |||||
| "description": "A path relative to 'src' inside the 'static' directory, for example 'static/images/logo.png'.", | ||||||
| "pattern": "^\\s*(?:\\.[\\\\/])?static(?:[\\\\/](?!\\.{1,2}(?:[\\\\/]|\\s*$))[^\\\\/]*[^\\\\/\\s][^\\\\/]*)+\\s*$" | ||||||
| }, | ||||||
| "httpsAddress": { | ||||||
| "type": "string", | ||||||
| "description": "An address starting with 'https://' and a host, with no spaces.", | ||||||
| "pattern": "^[hH][tT][tT][pP][sS]://[^\\s/\\\\?#]+(?:[/?#]\\S*)?$" | ||||||
| }, | ||||||
| "color": { | ||||||
| "type": "string", | ||||||
| "description": "#rgb or #rrggbb, for example '#1d4ed8'.", | ||||||
|
|
@@ -226,6 +231,19 @@ | |||||
| } | ||||||
| } | ||||||
| }, | ||||||
| "googleConsentMode": { | ||||||
| "type": "object", | ||||||
| "description": "Starts Google's own tags in Google's Consent Mode: they load at once, set no cookies and mark every hit as denied until your consent tool calls gtag('consent', 'update'). Other vendors' tags inside a Google Tag Manager container need consent checks of their own there. Set it when a consent banner decides what is tracked. It holds back no script listed in 'scripts'.", | ||||||
| "additionalProperties": false, | ||||||
| "required": ["default"], | ||||||
| "properties": { | ||||||
| "default": { | ||||||
| "type": "string", | ||||||
| "enum": ["denied"], | ||||||
| "description": "What the tags take a reader's answer to be until your consent tool gives one." | ||||||
| } | ||||||
| } | ||||||
| }, | ||||||
| "keepQueryParams": { | ||||||
| "type": "array", | ||||||
| "description": "Your own link tags to keep in reported page addresses. Campaign (utm_), ad-click and cross-domain tags are kept already; every other query parameter is dropped.", | ||||||
|
|
@@ -250,10 +268,40 @@ | |||||
| } | ||||||
| } | ||||||
| }, | ||||||
| "scripts": { | ||||||
| "type": "array", | ||||||
| "description": "Other vendors' scripts and widgets, loaded on every page in the listed order, except the OAuth callback page. They get the portal's events from window.apimatic.analytics.subscribe(). Any listed script can read what readers type into the API playground, so list only vendors you trust.", | ||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Tracked in apimatic/apimatic-io#2355: a listed script can read the token a reader gets from an OAuth 2.0 sign-in in the playground, which the playground keeps in session storage for the life of the tab. For this PR, please name that token here, as the docs draft (apimatic/apimatic-docs#887) already does. Owners read this description in their editor, and today it covers only what readers type:
Suggested change
The issue's other item for you is a Fumadocs issue asking the playground not to keep that token in session storage for the rest of the tab. |
||||||
| "items": { | ||||||
| "type": "object", | ||||||
| "additionalProperties": false, | ||||||
| "required": ["src", "category"], | ||||||
| "properties": { | ||||||
| "src": { | ||||||
| "description": "An address starting with 'https://' and a host, with no spaces, or a file in the 'static' directory, for example 'static/analytics.js'.", | ||||||
| "anyOf": [ | ||||||
| { | ||||||
| "$ref": "#/definitions/httpsAddress" | ||||||
| }, | ||||||
| { | ||||||
| "$ref": "#/definitions/staticPath" | ||||||
| } | ||||||
| ] | ||||||
| }, | ||||||
| "category": { | ||||||
| "type": "string", | ||||||
| "description": "What the script is for. --no-analytics leaves out the 'analytics' and 'marketing' scripts.", | ||||||
| "enum": ["necessary", "functional", "analytics", "marketing"] | ||||||
|
Comment on lines
+292
to
+293
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Please define the four categories, and say why there are four
So today the four names make a two-way choice. Could you:
|
||||||
| } | ||||||
| } | ||||||
| } | ||||||
| }, | ||||||
| "pluginUrl": { | ||||||
| "type": "string", | ||||||
| "description": "Where the context plugin is hosted, starting with 'https://' and with no spaces. The Context Plugin page installs it from here, and the portal carries no copy of its own.", | ||||||
| "pattern": "^[hH][tT][tT][pP][sS]://[^\\s/?#]+(?:[/?#]\\S*)?$" | ||||||
| "allOf": [ | ||||||
| { | ||||||
| "$ref": "#/definitions/httpsAddress" | ||||||
| } | ||||||
| ], | ||||||
| "description": "Where the context plugin is hosted, starting with 'https://' and with no spaces. The Context Plugin page installs it from here, and the portal carries no copy of its own." | ||||||
| } | ||||||
| } | ||||||
| }, | ||||||
|
|
||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| /** One portal event as a subscriber receives it. Customers' scripts read these keys, so `version` moves if one ever changes. */ | ||
| export interface PortalEvent { | ||
| readonly name: string; | ||
| /** The event's details, with `page_location` among them. */ | ||
| readonly params: Readonly<Record<string, string | number>>; | ||
| /** When it was reported, in milliseconds since the epoch. */ | ||
| readonly time: number; | ||
| readonly version: 1; | ||
| } | ||
|
|
||
| type Subscriber = (event: PortalEvent) => void; | ||
| type Unsubscribe = () => void; | ||
|
|
||
| interface Subscription { | ||
| callback: Subscriber; | ||
| deliveredCount: number; | ||
| } | ||
|
|
||
| /** A window's events, for the scripts in it: a subscriber gets every one reported so far, then each new one. */ | ||
| export class EventFeed { | ||
| private readonly events: PortalEvent[] = []; | ||
| private readonly subscriptions = new Set<Subscription>(); | ||
|
|
||
| public subscribe(callback: Subscriber): Unsubscribe { | ||
| if (typeof callback !== 'function') { | ||
| throw new TypeError('window.apimatic.analytics.subscribe() takes a function.'); | ||
| } | ||
| const subscription: Subscription = { callback, deliveredCount: 0 }; | ||
| this.subscriptions.add(subscription); | ||
| // Once this has returned, so a callback can call the function it returns, even for an earlier event. | ||
| queueMicrotask(() => EventFeed.deliver(this, subscription)); | ||
| return () => { | ||
| this.subscriptions.delete(subscription); | ||
| }; | ||
| } | ||
|
|
||
| public publish(name: string, params: Record<string, string | number>): void { | ||
| // A copy, frozen, so no subscriber changes what the next one gets, or what the data layer was handed. | ||
| this.events.push(Object.freeze({ name, params: Object.freeze({ ...params }), time: Date.now(), version: 1 })); | ||
| // The set itself: one a callback adds is reached in this same pass, and one it removes is skipped. | ||
| for (const subscription of this.subscriptions) EventFeed.deliver(this, subscription); | ||
| } | ||
|
|
||
| private static deliver(feed: EventFeed, subscription: Subscription): void { | ||
| // Called on its own, so a callback written without strict mode finds the window as `this`, never this record. | ||
| const { callback } = subscription; | ||
| while (feed.subscriptions.has(subscription) && subscription.deliveredCount < feed.events.length) { | ||
| const event = feed.events[subscription.deliveredCount]; | ||
| subscription.deliveredCount += 1; | ||
| try { | ||
| callback(event); | ||
| } catch (error) { | ||
| // Thrown later, so it shows in the console and stops neither the next event nor the next subscriber. | ||
| setTimeout(() => { | ||
| throw error; | ||
| }); | ||
| } | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggest rewording the last sentence:
wait_for_update's 500 ms).'scripts'sits underportal.analyticshere, so it can read as a sibling ofgoogleConsentMode. The full path matches the--no-analyticshelp text.