Skip to content

📝 Revise Include custom JavaScript in AMP pages #3376

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

Merged
sebastianbenz merged 1 commit into from
Jan 17, 2020
Merged

📝 Revise Include custom JavaScript in AMP pages #3376

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions ...content/amp-dev/documentation/guides-and-tutorials/develop/custom-javascript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ contributors:
description: For web experiences requiring a high amount of customization AMP has created amp-script, a component that allows the use of arbitrary JavaScript on your AMP page without affecting the page's overall performance.
---

AMP strives to provide a consistently good experience to all users across the web by encouraging the use of high-functioning and seamless components that are ready to go out of the box.
AMP strives to provide a consistently great experience to all users across the web by encouraging the use of high-functioning and seamless components that are ready to go out of the box.

Some web experiences require a high amount of customization that go beyond the state binding capabilities of [`amp-bind`](../../../documentation/components/reference/amp-bind.md?format=websites) and the dynamic data retrieval and templating functionality of [`amp-list`](../../../documentation/components/reference/amp-list.md?format=websites) and [`amp-mustache`](../../../documentation/components/reference/amp-mustache.md?format=websites). For those one-off cases, AMP has created [`<amp-script>`](../../../documentation/components/reference/amp-script.md?format=websites), a component that allows the use of arbitrary JavaScript on your AMP page without affecting the page's overall performance.
Some web experiences require a high amount of customization that goes beyond the state binding capabilities of [`amp-bind`](../../../documentation/components/reference/amp-bind.md?format=websites) and the dynamic data retrieval and templating functionality of [`amp-list`](../../../documentation/components/reference/amp-list.md?format=websites) and [`amp-mustache`](../../../documentation/components/reference/amp-mustache.md?format=websites). For those one-off cases, AMP has created [`<amp-script>`](../../../documentation/components/reference/amp-script.md?format=websites), a component that allows the use of arbitrary JavaScript on your AMP page without affecting the page's overall performance.

# Inserting custom JavaScript

Expand Down Expand Up @@ -39,13 +39,13 @@ The `amp-script` component sends messages between the Web Worker thread and the

## Custom scripts caching

The [AMP cache](../../../documentation/guides-and-tutorials/learn/amp-caches-and-cors/how_amp_pages_are_cached.md) serves custom JavaScript files inserted with `<amp-script>` same as AMP component scripts. This ensures that any custom JavaScript will not slow the speed of an AMP document.
The [AMP cache](../../../documentation/guides-and-tutorials/learn/amp-caches-and-cors/how_amp_pages_are_cached.md) serves custom JavaScript files inserted with `<amp-script>` the same way it serves AMP component scripts, which ensures that any custom JavaScript will not slow the speed of an AMP document.

The AMP cache proxies the JavaScript files and then delivers them. Users can expect the same performance experience from a page using `<amp-script>` as a page that doesn't include it.

# Using `<amp-script>`

To keep experiences on AMP pages consistent, limitations exist on `<amp-script>` to guarantee a fast loading time and smooth UI.
To guarantee AMP pages will load consistently fast and with smooth UIs, limitations exist on `<amp-script>`.

## Initialization

Expand All @@ -72,19 +72,19 @@ For user experience and security reasons, `amp-script` enforces DOM manipulation

### User interaction

When a user interacts with elements wrapped inside an `<amp-script>` component, your custom JavaScript must return DOM manipulations quickly when needed. By default, changes to the DOM are permitted **less than one second** from the initial interaction. A notable exception is when your code must retrieve data from the network via `fetch`. Here DOM changes can be requested after the response is returned to the user and for **less than one second** afterwards. If a script mutates the DOM outside of a permitted window, this will result in a fatal error and the `<amp-script>` component will terminate the Web Worker. A terminated `<amp-script>` component will not run again.
When a user interacts with elements wrapped inside an `<amp-script>` component, your custom JavaScript must return DOM manipulations quickly when needed. By default, changes to the DOM are permitted **less than one second** from the initial interaction. A notable exception is when your code must retrieve data from the network via `fetch`. Here DOM changes can be requested after the response is returned to the user and for **less than one second** afterward. If a script mutates the DOM outside of a permitted window, this will result in a fatal error and the `<amp-script>` component will terminate the Web Worker. A terminated `<amp-script>` component will not run again.

### Unprompted changes

There is no user interaction required to manipulate the DOM if the `<amp-script>` component has a fixed height.

## Script size

AMP enforces a limit of 150 kilobytes of custom JavaScript on each page. This limit is shared among all `<amp-script>` component on that page. Any external JavaScript library must be imported to each individual `<amp-script>` component.
AMP enforces a limit of 150 kilobytes of custom JavaScript on each page. This limit is shared among all `<amp-script>` components on that page. Any external JavaScript library must be imported to each individual `<amp-script>` component.

## Scope

Any DOM elements the custom JavaScript files wishes to interact with must be wrapped inside the `<amp-script>` component tags. This includes other AMP components. The `<amp-script>` component considers `document.body` to be the `<amp-script>` element and not the document's `<body>` element.
Any DOM elements the custom JavaScript files wish to interact with must be wrapped inside the `<amp-script>` component tags. This includes other AMP components. The `<amp-script>` component considers `document.body` to be the `<amp-script>` element and not the document's `<body>` element.

If you were to call `document.body.appendChild(document.createElement('span'))` within the script imported into an `<amp-script>` element in the following document:

Expand Down