💉 PlayPilot Link Injections

Link Injections (also called TPI (Text Playlink Injection) and ALI (Article Link Injection)) adds links to any page content. These links open a popover or modal with relevant information for any given movie or show. Alternatively, they link directly to the related PlayPilot page.

Development

Start development server using:

npm run dev

The dev environment will be available at:

localhost:3000

Only the root page has content. This page contains multiple examples different injection scenarios, some real, some made up. Some of these are intentionally tricky to parse, but have come up as real examples in the past.

Build

To build the final script simply run npm run build.

The final build differs largely from the development environment. The development environment uses SvelteKit, but the final build only uses Svelte which is build to a single file that includes all images, css, and of course the javascript itself. This file is output to /dist/link-injections.js. This file is included in the repo.

Publishing

The project is published on NPM as a package, but only the final dist file is relevant. This file is included in the repo so that it can be picked up by jsdelivr.net, which we use as a CDN for the script. The url that is presented to clients is a redirect from https://scripts.playpilot.com/link-injection.js to https://cdn.jsdelivr.net/npm/@playpilot/tpi@[version]/dist/link-injections.js. We use a direct version rather than @latest to have better control over caching, as @latest is cached both on jsdelivr and the end user's browser.

The build and publish a new version simply run:

npm run release major|minor|patch

To publish the script manually follow these steps (this is often done for beta versions):

1. Build the script using `npm run build, optionally commit the new file as a separate commit
2. Bump the package.json version, optionally commit this change
3. Publish the script using npm publish --access public (or npm publish --access public --tag next for beta versions)
4. Update redirect rules on Cloudflare to match the new version, which can be found under the "TPI: Latest script version (jsdelivr)" rule (or "TPI: Beta script version (jsdelivr)" for beta versions).

Notes

The script inserts elements right on the page it is used, because of that all elements relevant to the script automatically inherit styling from the page. Because of this it's very important to adhere to some rules:

• Avoid semantics tags. Tags such as h1, header, p, and more, are convenient but are very likely to be styled quite specifically. Instead, stick to general elements such as div and span, but with proper attributes. A heading might use div role=heading level=2, a dialog might use div role=dialog. While this doesn't do anything visually, it keeps accessibility features intact.
• Do not use global styling.. Styling from the page leaks into element from our script, but the opposit is also true. Any global styling we apply will apply to the page itself. Stick to scoped styling either via styling in Svelte components, or stick to very specific class names either on the elements themselves or as parents. src/lib/scss/global.scss holds such elements. Some other global css in included in src/routes/+page.svelte`
• Use css variables for styling. All elements that are displayed on the page might need to be styled to match the page. This is done through css variables rather than just overwriting style via selectors. This makes it easier for us to change styling without having to worry about updating partner specific styling. These css variables often have other css variables as fallbacks, and are always prefixed with --playpilot. For instance var(--playpilot-dialog-background, var(--playpilot-light)). This can be further expanded to var(--playpilot-title-background, var(--playpilot-dialog-background, var(--playpilot-light))). In this case all default styling is still handled through our own styling --playpilot-light, but can be overwritten on all relevant elements with --playpilot-dialog-background, and more specifically with --playpilot-title-background.
• Avoid external libraries. The script is meant to be as lean as possible, it needs to load quickly. External libraries by nature contain things we don't need and add unnecessary bloat. That's not always true, so use your best judgement. This only includes libraries that would be included in the final build of course.
• Do not use non-vector images within the script. The script is compiled to a single file. Including non-vector images will lead to a much larger file size as these images will need to be inlined and this is not compressable. Stick to SVGs and make sure these SVGs are inlined.