diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index a8e26832e299..2d3ced7aedb1 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1,9 +1,13 @@ **Please only file bugs/feature requests for AMP here.** -- If you have questions about how to use AMP or other general questions about AMP please ask them on Stack Overflow under the AMP HTML tag instead of filing an issue here: http://stackoverflow.com/questions/tagged/amp-html -- If you have questions/issues related to Google Search please ask them in Google's AMP forum instead of filing an issue here: https://goo.gl/utQ1KZ +- If you have questions about how to use AMP or other general questions about + AMP please ask them on Stack Overflow under the AMP HTML tag instead of filing + an issue here: http://stackoverflow.com/questions/tagged/amp-html +- If you have questions/issues related to Google Search please ask them in + Google's AMP forum instead of filing an issue here: https://goo.gl/utQ1KZ -If you have a bug or feature request for AMP please fill in the following template. Delete everything except the headers (including this text). +If you have a bug or feature request for AMP please fill in the following +template. Delete everything except the headers (including this text). ## What's the issue? @@ -11,17 +15,24 @@ Briefly describe the bug/feature request. ## How do we reproduce the issue? -If this is a bug please provide a public URL and ideally a reduced test case (e.g. on jsbin.com, codepen.io, or glitch.com) that exhibits only your issue and nothing else. Then provide step-by-step instructions for reproducing the issue: +If this is a bug please provide a public URL and ideally a reduced test case +(e.g. on jsbin.com, codepen.io, or glitch.com) that exhibits only your issue and +nothing else. Then provide step-by-step instructions for reproducing the issue: 1. Step 1 to reproduce 2. Step 2 to reproduce 3. … -If this is a feature request you can use this section to point to a prototype/mockup that will help us understand the request. +If this is a feature request you can use this section to point to a +prototype/mockup that will help us understand the request. ### Tips on Rendering Bugs -If you're reporting a bug that's the result of rendering data from an endpoint (e.g. with `` or ``), it's helpful to include sample JSON data from your endpoint. [JSONPlaceholder](https://jsonplaceholder.typicode.com/) is great for providing publicly accessible sample endpoint as well as dummy json endpoints. +If you're reporting a bug that's the result of rendering data from an endpoint +(e.g. with `` or ``), it's helpful to include sample JSON +data from your endpoint. +[JSONPlaceholder](https://jsonplaceholder.typicode.com/) is great for providing +publicly accessible sample endpoint as well as dummy json endpoints. ## What browsers are affected? @@ -29,4 +40,5 @@ All browsers? Some specific browser? What device type? ## Which AMP version is affected? -Is this a new issue? Or was it always broken? Paste your AMP version. You can find it in the browser dev tools. +Is this a new issue? Or was it always broken? Paste your AMP version. You can +find it in the browser dev tools. diff --git a/.prettierrc b/.prettierrc index ff0aac584cbb..8585d42074f9 100644 --- a/.prettierrc +++ b/.prettierrc @@ -10,7 +10,11 @@ }, { "files": "*.md", - "options": {"parser": "markdown"} + "options": { + "proseWrap": "always", + "printWidth": 80, + "parser": "markdown" + } }, { "files": [".eslintrc", ".prettierrc", ".renovaterc.json", "*.json"], diff --git a/3p/README.md b/3p/README.md index 145340275765..526284b81024 100644 --- a/3p/README.md +++ b/3p/README.md @@ -1,55 +1,92 @@ # Inclusion of third party software, embeds, and services into AMP -In general all inclusions are subject to [CONTRIBUTING.md](../CONTRIBUTING.md). This files outlines specific rules for certain types of external embed and other software inclusions. +In general all inclusions are subject to [CONTRIBUTING.md](../CONTRIBUTING.md). +This files outlines specific rules for certain types of external embed and other +software inclusions. -In order to qualify for inclusion, an extended component that integrates a third-party service must generally meet the notability requirements of the English Wikipedia, and is in common use in Internet publishing. As a rough rule of thumb, it should be used or requested by 5% of the top 10,000 websites as noted on builtwith.com, or already integrated into [oEmbed](http://oembed.com/). +In order to qualify for inclusion, an extended component that integrates a +third-party service must generally meet the notability requirements of the +English Wikipedia, and is in common use in Internet publishing. As a rough rule +of thumb, it should be used or requested by 5% of the top 10,000 websites as +noted on builtwith.com, or already integrated into [oEmbed](http://oembed.com/). -We highly prefer integrations that do not use iframes. JSONP cannot be used for security reasons, but CORS requests are perfectly fine. +We highly prefer integrations that do not use iframes. JSONP cannot be used for +security reasons, but CORS requests are perfectly fine. ## Embeds -Examples: Youtube, Vimeo videos; Tweets, Instagrams; comment systems; polls; quizzes; document viewers +Examples: Youtube, Vimeo videos; Tweets, Instagrams; comment systems; polls; +quizzes; document viewers -- Our intent is to provide first class support for all embeds that fulfill the notability guidelines laid out in [CONTRIBUTING.md](../CONTRIBUTING.md). -- Consider whether a iframe-with-placeholder solution fits your use case where iframe generation is not done immediately (can be done before user action for instant loading of iframe). -- Consider whether all that is needed is some documentation for how to use the embed with `amp-iframe`. +- Our intent is to provide first class support for all embeds that fulfill the + notability guidelines laid out in [CONTRIBUTING.md](../CONTRIBUTING.md). +- Consider whether a iframe-with-placeholder solution fits your use case where + iframe generation is not done immediately (can be done before user action for + instant loading of iframe). +- Consider whether all that is needed is some documentation for how to use the + embed with `amp-iframe`. - Iframes and all sub resources must be served from HTTPS. - Avoid client side rendering of iframe content. -- If your use of iframes is for style isolation, consider that AMP might provide an iframe-free alternative. -- If you can make it not-iframe-based that is much better. (See e.g. the pinterest embed). We will always ask to do this first. E.g. adding a CORS endpoint to your server might make this possible. -- Must play well within [AMP's sizing framework](https://github.com/ampproject/amphtml/blob/master/spec/amp-html-layout.md). +- If your use of iframes is for style isolation, consider that AMP might provide + an iframe-free alternative. +- If you can make it not-iframe-based that is much better. (See e.g. the + pinterest embed). We will always ask to do this first. E.g. adding a CORS + endpoint to your server might make this possible. +- Must play well within + [AMP's sizing framework](https://github.com/ampproject/amphtml/blob/master/spec/amp-html-layout.md). - All JS on container page must be open source and bundled with AMP. -- JavaScript loaded into iframe should be reasonable with respect to functionality. +- JavaScript loaded into iframe should be reasonable with respect to + functionality. - Use the `sandbox` attribute on iframe if possible. - Provide unit and [integration tests](#adding-proper-integration-tests). -- Embeds that require browser plugins, such as Flash, Java, ActiveX, Silverlight, etc. are disallowed unless necessary. Special review required. We cannot currently see a reason why these should be allowed. +- Embeds that require browser plugins, such as Flash, Java, ActiveX, + Silverlight, etc. are disallowed unless necessary. Special review required. We + cannot currently see a reason why these should be allowed. ## Ads - We welcome pull requests by all ad networks for inclusion into AMP. - All ads and all sub resources must be served from HTTPS. -- Must play well within [AMP's sizing framework](https://github.com/ampproject/amphtml/blob/master/spec/amp-html-layout.md). -- For display ads support, always implement amp-ad and instruct your client to use your amp-ad implementation instead of using amp-iframe. Althought amp-iframe will render the ad, ad clicks will break and viewability information is not available. +- Must play well within + [AMP's sizing framework](https://github.com/ampproject/amphtml/blob/master/spec/amp-html-layout.md). +- For display ads support, always implement amp-ad and instruct your client to + use your amp-ad implementation instead of using amp-iframe. Althought + amp-iframe will render the ad, ad clicks will break and viewability + information is not available. - Providing an optional image only zero-iframe embed is appreciated. -- Support viewability and other metrics/instrumentation as supplied by AMP (via postMessage API) +- Support viewability and other metrics/instrumentation as supplied by AMP (via + postMessage API) - Try to keep overall iframe count at one per ad. Explain why more are needed. - Share JS between iframes on the same page. - Provide unit and [integration tests](#adding-proper-integration-tests). -- Provide test accounts for inclusion in our open source repository for integration tests. - -The following aren't hard requirements, but are performance optimizations we should strive to incorporate. Please provide a timeline as to when you expect to follow these guidelines: - -- Support pause and play APIs to turn animations on and off. Ideally also to interrupt loading. -- Never block the UI thread for longer than 50ms, so that user action is never blocked for longer than that. - - Keep individual JS files small enough, so they compile in under 50ms on a 2013 Android phone. +- Provide test accounts for inclusion in our open source repository for + integration tests. + +The following aren't hard requirements, but are performance optimizations we +should strive to incorporate. Please provide a timeline as to when you expect to +follow these guidelines: + +- Support pause and play APIs to turn animations on and off. Ideally also to + interrupt loading. +- Never block the UI thread for longer than 50ms, so that user action is never + blocked for longer than that. + - Keep individual JS files small enough, so they compile in under 50ms on a + 2013 Android phone. - Split up other expensive work, so it can be interrupted at 50ms boundary. - Creatives should only use animations drive by CSS animation frame. - Creatives should only animate using CSS transforms and opacity. -- When creatives animate they should not use more than 2ms time per frame to allow for other animations to have sufficient time for concurrent animations. +- When creatives animate they should not use more than 2ms time per frame to + allow for other animations to have sufficient time for concurrent animations. -The better an ad network does on the above requirements, the earlier ads from it will be loaded into AMP. In other words: _The slower the ad loads and the more it interferes with the page, the later AMP will load it._ +The better an ad network does on the above requirements, the earlier ads from it +will be loaded into AMP. In other words: _The slower the ad loads and the more +it interferes with the page, the later AMP will load it._ -We are also excited to start conversations how modern web tech could improve overall ads latency, memory usage and framerate impact and how AMP's open source model could be used to inject trust through an auditable common code base into the ads ecosystem which would reduce the necessity of redundant metrics collection. +We are also excited to start conversations how modern web tech could improve +overall ads latency, memory usage and framerate impact and how AMP's open source +model could be used to inject trust through an auditable common code base into +the ads ecosystem which would reduce the necessity of redundant metrics +collection. Review the [ads/README](../ads/README.md) for further details on ad integration. @@ -57,14 +94,23 @@ Review the [ads/README](../ads/README.md) for further details on ad integration. - AMP allows inclusion of fonts via the `@font-face` directive. - JavaScript can not be involved with the initiation of font loading. -- Font loading gets controlled (but not initiated) by [``](https://github.com/ampproject/amphtml/issues/648). -- AMP by default does not allow inclusion of external stylesheets, but it is happy to whitelist URL prefixes of font providers for font inclusion via link tags. These link tags and their fonts must be served via HTTPS. -- If a font provider does referrer based "security" it needs to whitelist the AMP proxy origins before being included in the link tag whitelist. AMP proxy sends the appropriate referrer header such as `https://cdn.ampproject.org` and `https://amp.cloudflare.com`. +- Font loading gets controlled (but not initiated) by + [``](https://github.com/ampproject/amphtml/issues/648). +- AMP by default does not allow inclusion of external stylesheets, but it is + happy to whitelist URL prefixes of font providers for font inclusion via link + tags. These link tags and their fonts must be served via HTTPS. +- If a font provider does referrer based "security" it needs to whitelist the + AMP proxy origins before being included in the link tag whitelist. AMP proxy + sends the appropriate referrer header such as `https://cdn.ampproject.org` and + `https://amp.cloudflare.com`. # Adding proper integration tests -You should ensure there are integration tests for your extension. These should be added to the AMP -repo where it makes sense. In some cases this won't be possible because it relies on bringing up -third-party infrastructure. In these cases you should maintain testing for the extension on your -infrastructure against both production AMP and [canary](https://github.com/ampproject/amphtml/blob/master/contributing/release-schedule.md#amp-dev-channel). -Upon any monitored failures, an escalation can be raised in [regular AMP communication channel](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md#discussion-channels). +You should ensure there are integration tests for your extension. These should +be added to the AMP repo where it makes sense. In some cases this won't be +possible because it relies on bringing up third-party infrastructure. In these +cases you should maintain testing for the extension on your infrastructure +against both production AMP and +[canary](https://github.com/ampproject/amphtml/blob/master/contributing/release-schedule.md#amp-dev-channel). +Upon any monitored failures, an escalation can be raised in +[regular AMP communication channel](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md#discussion-channels). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 78883b3ab4b9..8fbdf422a243 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,11 @@ # Contributing to AMP HTML -The AMP HTML project strongly encourages your participation and [contributions](https://www.ampproject.org/contribute/)! +The AMP HTML project strongly encourages your participation and +[contributions](https://www.ampproject.org/contribute/)! -We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about. +We hope you'll become an ongoing participant in our open source community but we +also welcome one-off contributions for the issues you're particularly passionate +about. How would you like to help? @@ -12,37 +15,65 @@ How would you like to help? - [Get started with open source](#get-started-with-open-source) - [Participate in ongoing discussions](#ongoing-participation) -If you have questions about _using_ AMP or are _encountering problems using AMP_ on your site please visit our [support page](SUPPORT.md) for help. +If you have questions about _using_ AMP or are _encountering problems using AMP_ +on your site please visit our [support page](SUPPORT.md) for help. ## Report a bug -[File an issue](https://github.com/ampproject/amphtml/issues/new?assignees=&labels=Type%3A+Bug&template=bug-report.md&title=) if you find a bug in AMP. Provide a detailed description and steps for reproducing the bug; screenshots and working examples that demonstrate the problem are appreciated! +[File an issue](https://github.com/ampproject/amphtml/issues/new?assignees=&labels=Type%3A+Bug&template=bug-report.md&title=) +if you find a bug in AMP. Provide a detailed description and steps for +reproducing the bug; screenshots and working examples that demonstrate the +problem are appreciated! -The community regularly monitoring issues and will try to fix open bugs quickly according to our [prioritization guidelines](./contributing/issue-priorities.md). +The community regularly monitoring issues and will try to fix open bugs quickly +according to our +[prioritization guidelines](./contributing/issue-priorities.md). ## Make a suggestion -[File a "feature request" issue](https://github.com/ampproject/amphtml/issues/new?assignees=&labels=Type%3A+Feature+Request&template=feature_request.md&title=) if you have a suggestion for a way to improve AMP or a request for a new AMP feature. +[File a "feature request" issue](https://github.com/ampproject/amphtml/issues/new?assignees=&labels=Type%3A+Feature+Request&template=feature_request.md&title=) +if you have a suggestion for a way to improve AMP or a request for a new AMP +feature. -If you are suggesting a feature that you are intending to implement, please see the [Contributing code/features](#contribute-code-features) section below for next steps. +If you are suggesting a feature that you are intending to implement, please see +the [Contributing code/features](#contribute-code-features) section below for +next steps. ## Contribute code/features We'd love to have your help contributing code and features to AMP! -See the [Contributing code and features](contributing/contributing-code.md) document for details on the process you can use to add code/features. +See the [Contributing code and features](contributing/contributing-code.md) +document for details on the process you can use to add code/features. ## Get started with open source -If you are new to contributing to an open source project, Git/GitHub, etc. welcome! We are glad you're interested in contributing to AMP and we want to help make your open source experience a success. - -The [Getting Started End-to-End Guide](./contributing/getting-started-e2e.md) provides step-by-step instructions for everything from creating a GitHub account to getting your code reviewed and merged. Even if you've never contributed to an open source project before you'll soon be building AMP, making improvements and seeing your code live across the web. - -The community has created a list of [Good First Issues](https://github.com/ampproject/amphtml/labels/good%20first%20issue) specifically for new contributors to the project. Feel free to find one of the [unclaimed Good First Issues](https://github.com/ampproject/amphtml/issues?utf8=%E2%9C%93&q=is%3Aopen%20label%3A%22good%20first%20issue%22%20-label%3A%22GFI%20Claimed!%22) that interests you, claim it by adding a comment to it and jump in! - -If you're interested in helping out but can't find a Good First Issue that matches your skills/interests, [sign up for our Slack](https://bit.ly/amp-slack-signup) and then reach out in the [#welcome-contributors channel](https://amphtml.slack.com/messages/welcome-contributors/) or send a Direct Message to [mrjoro](https://amphtml.slack.com/team/mrjoro/). - -If you run into any problems we have plenty of people who are willing to help; see the [How to get help](./contributing/getting-started-e2e.md#how-to-get-help) section of the Getting Started guide. +If you are new to contributing to an open source project, Git/GitHub, etc. +welcome! We are glad you're interested in contributing to AMP and we want to +help make your open source experience a success. + +The [Getting Started End-to-End Guide](./contributing/getting-started-e2e.md) +provides step-by-step instructions for everything from creating a GitHub account +to getting your code reviewed and merged. Even if you've never contributed to an +open source project before you'll soon be building AMP, making improvements and +seeing your code live across the web. + +The community has created a list of +[Good First Issues](https://github.com/ampproject/amphtml/labels/good%20first%20issue) +specifically for new contributors to the project. Feel free to find one of the +[unclaimed Good First Issues](https://github.com/ampproject/amphtml/issues?utf8=%E2%9C%93&q=is%3Aopen%20label%3A%22good%20first%20issue%22%20-label%3A%22GFI%20Claimed!%22) +that interests you, claim it by adding a comment to it and jump in! + +If you're interested in helping out but can't find a Good First Issue that +matches your skills/interests, +[sign up for our Slack](https://bit.ly/amp-slack-signup) and then reach out in +the +[#welcome-contributors channel](https://amphtml.slack.com/messages/welcome-contributors/) +or send a Direct Message to [mrjoro](https://amphtml.slack.com/team/mrjoro/). + +If you run into any problems we have plenty of people who are willing to help; +see the [How to get help](./contributing/getting-started-e2e.md#how-to-get-help) +section of the Getting Started guide. ## Ongoing participation @@ -52,20 +83,37 @@ We actively encourage ongoing participation by community members. Technical issues, designs, etc. are discussed using several different channels: -- [GitHub issues](https://github.com/ampproject/amphtml/issues) and [pull requests](https://github.com/ampproject/amphtml/pulls) +- [GitHub issues](https://github.com/ampproject/amphtml/issues) and + [pull requests](https://github.com/ampproject/amphtml/pulls) - [Slack](https://amphtml.slack.com) ([signup](https://bit.ly/amp-slack-signup)) - - the [#contributing](https://amphtml.slack.com/messages/C9HRJ1GPN/details/) channel is the main channel for you to discuss/ask questions about _contributing_ to the open source project - - if you're _new to contributing_ to AMP stop by [#welcome-contributors](https://amphtml.slack.com/messages/C432AFMFE/details/) to say hi! - - **NOTE: if you have a question about _using AMP on your site_, use [Stack Overflow](https://stackoverflow.com/questions/tagged/amp-html) rather than Slack** as Stack Overflow is more actively monitored for these types of questions - - there are many other Slack channels for more specific topics; after you join our Slack click on the "Channels" header to find other channels you want to participate in -- the [amphtml-discuss Google Group](https://groups.google.com/forum/#!forum/amphtml-discuss) + - the [#contributing](https://amphtml.slack.com/messages/C9HRJ1GPN/details/) + channel is the main channel for you to discuss/ask questions about + _contributing_ to the open source project + - if you're _new to contributing_ to AMP stop by + [#welcome-contributors](https://amphtml.slack.com/messages/C432AFMFE/details/) + to say hi! + - **NOTE: if you have a question about _using AMP on your site_, use + [Stack Overflow](https://stackoverflow.com/questions/tagged/amp-html) rather + than Slack** as Stack Overflow is more actively monitored for these types of + questions + - there are many other Slack channels for more specific topics; after you join + our Slack click on the "Channels" header to find other channels you want to + participate in +- the + [amphtml-discuss Google Group](https://groups.google.com/forum/#!forum/amphtml-discuss) ### Working groups -Most of the day-to-day work in building AMP happens in AMP's [Working Groups (WGs)](https://github.com/ampproject/meta/tree/master/working-groups). Getting involved in a WG is a great way to contribute to AMP. +Most of the day-to-day work in building AMP happens in AMP's +[Working Groups (WGs)](https://github.com/ampproject/meta/tree/master/working-groups). +Getting involved in a WG is a great way to contribute to AMP. -Most working groups post approximately bi-weekly [Status Update GitHub issues](https://github.com/search?q=org%3Aampproject+label%3A%22Type%3A+Status+Update%22&type=Issues). +Most working groups post approximately bi-weekly +[Status Update GitHub issues](https://github.com/search?q=org%3Aampproject+label%3A%22Type%3A+Status+Update%22&type=Issues). ### Weekly design reviews -The community holds weekly engineering [design reviews](./contributing/design-reviews.md) via video conference. We encourage everyone in the community to participate in these discussions and to bring their designs for new features and significant bug fixes to these reviews. +The community holds weekly engineering +[design reviews](./contributing/design-reviews.md) via video conference. We +encourage everyone in the community to participate in these discussions and to +bring their designs for new features and significant bug fixes to these reviews. diff --git a/README.md b/README.md index 3bf2174029e4..3f5fde723442 100644 --- a/README.md +++ b/README.md @@ -34,13 +34,15 @@ Tooling -[AMP](https://amp.dev) is a web component framework for easily creating user-first websites, stories, ads, emails and more. +[AMP](https://amp.dev) is a web component framework for easily creating +user-first websites, stories, ads, emails and more. AMP is an open source project, and we'd love your help making it better! ## Want to know more about AMP? -- [amp.dev](https://amp.dev) is the best place to learn more about AMP--and of course the site is made using AMP! +- [amp.dev](https://amp.dev) is the best place to learn more about AMP--and of + course the site is made using AMP! - For developers using AMP, amp.dev includes - [guides and tutorials](https://amp.dev/documentation/guides-and-tutorials/) - [examples](https://amp.dev/documentation/examples/) @@ -50,21 +52,43 @@ AMP is an open source project, and we'd love your help making it better! ## Having a problem using AMP? -- The [amp.dev Support page](https://amp.dev/support/) has resources for getting help. -- Use [Stack Overflow](http://stackoverflow.com/questions/tagged/amp-html) to ask questions about using AMP and find answers to questions others have asked. -- [Let us know about bugs](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md#report-a-bug), and [file feature requests](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md#make-a-suggestion) to suggest improvements. -- AMP accepts responsible security disclosures through the [Google Application Security program](https://www.google.com/about/appsecurity/). +- The [amp.dev Support page](https://amp.dev/support/) has resources for getting + help. +- Use [Stack Overflow](http://stackoverflow.com/questions/tagged/amp-html) to + ask questions about using AMP and find answers to questions others have asked. +- [Let us know about bugs](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md#report-a-bug), + and + [file feature requests](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md#make-a-suggestion) + to suggest improvements. +- AMP accepts responsible security disclosures through the + [Google Application Security program](https://www.google.com/about/appsecurity/). ## Want to help make AMP better? -- [CONTRIBUTING.md](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md) has information on how you can help improve AMP, including [ongoing participation](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md#ongoing-participation) through Slack, weekly design reviews, etc. -- We strongly encourage [code contributions](https://github.com/ampproject/amphtml/blob/master/contributing/contributing-code.md)! -- **We enthusiastically welcome new contributors to AMP _even if you have no experience being part of an open source project_**. We've made it easy to [get started contributing](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md#get-started-with-open-source). -- Consider joining one of AMP's [Working Groups](https://github.com/ampproject/meta/tree/master/working-groups), where most of the day-to-day work in AMP gets done. +- [CONTRIBUTING.md](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md) + has information on how you can help improve AMP, including + [ongoing participation](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md#ongoing-participation) + through Slack, weekly design reviews, etc. +- We strongly encourage + [code contributions](https://github.com/ampproject/amphtml/blob/master/contributing/contributing-code.md)! +- **We enthusiastically welcome new contributors to AMP _even if you have no + experience being part of an open source project_**. We've made it easy to + [get started contributing](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md#get-started-with-open-source). +- Consider joining one of AMP's + [Working Groups](https://github.com/ampproject/meta/tree/master/working-groups), + where most of the day-to-day work in AMP gets done. ## Other useful information -- [AMP's release documentation](contributing/release-schedule.md) provides details on how and when AMP releases new versions, including [how to know when a change is live in a release](https://github.com/ampproject/amphtml/blob/master/contributing/release-schedule.md#determining-if-your-change-is-in-a-release). -- [AMP's roadmap](https://amp.dev/community/roadmap) provides details on some of the significant projects we are working on. -- The [AMP meta repository](https://github.com/ampproject/meta) has information _about_ the AMP open source project, including AMP's [governance](https://github.com/ampproject/meta/blob/master/GOVERNANCE.md). -- [AMP's code of conduct](https://github.com/ampproject/meta/blob/master/CODE_OF_CONDUCT.md) documents how all members, committers and volunteers in the community are required to act. AMP strives for a positive and growing project community that provides a safe environment for everyone. +- [AMP's release documentation](contributing/release-schedule.md) provides + details on how and when AMP releases new versions, including + [how to know when a change is live in a release](https://github.com/ampproject/amphtml/blob/master/contributing/release-schedule.md#determining-if-your-change-is-in-a-release). +- [AMP's roadmap](https://amp.dev/community/roadmap) provides details on some of + the significant projects we are working on. +- The [AMP meta repository](https://github.com/ampproject/meta) has information + _about_ the AMP open source project, including AMP's + [governance](https://github.com/ampproject/meta/blob/master/GOVERNANCE.md). +- [AMP's code of conduct](https://github.com/ampproject/meta/blob/master/CODE_OF_CONDUCT.md) + documents how all members, committers and volunteers in the community are + required to act. AMP strives for a positive and growing project community that + provides a safe environment for everyone. diff --git a/SUPPORT.md b/SUPPORT.md index dc432985105e..9dbac7181fce 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -6,21 +6,37 @@ There are many ways to get help for questions and issues related to AMP: **Need help with AMP?** -If you are looking for help to get started using AMP on your site or you are having issues using AMP, consult these resources: - -- [Official documentation](https://amp.dev/documentation/guides-and-tutorials/) with guides and tutorials to help you learn about AMP. -- [Hands-on samples and demos](https://amp.dev/documentation/examples/) for using AMP components. -- [Pre-styled templates and components](https://amp.dev/documentation/templates/) that you can use to create styled AMP sites from scratch. -- [AMP tools](https://amp.dev/documentation/tools) helping you get started with building AMP pages. -- [AMP supported browsers](https://amp.dev/support/faq/supported-browsers) to learn which browsers support AMP. -- [Stack Overflow](http://stackoverflow.com/questions/tagged/amp-html) is our recommended way to find answers to questions about AMP; since members of the AMP Project community regularly monitor Stack Overflow you will probably receive the fastest response to your questions there. -- For AMP on Google Search questions or issues, please use [Google's AMP forum](https://goo.gl/utQ1KZ). -- To check the status of AMP serving and its related services, see the [AMP Status](https://status.ampproject.org/) page. +If you are looking for help to get started using AMP on your site or you are +having issues using AMP, consult these resources: + +- [Official documentation](https://amp.dev/documentation/guides-and-tutorials/) + with guides and tutorials to help you learn about AMP. +- [Hands-on samples and demos](https://amp.dev/documentation/examples/) for + using AMP components. +- [Pre-styled templates and components](https://amp.dev/documentation/templates/) + that you can use to create styled AMP sites from scratch. +- [AMP tools](https://amp.dev/documentation/tools) helping you get started with + building AMP pages. +- [AMP supported browsers](https://amp.dev/support/faq/supported-browsers) to + learn which browsers support AMP. +- [Stack Overflow](http://stackoverflow.com/questions/tagged/amp-html) is our + recommended way to find answers to questions about AMP; since members of the + AMP Project community regularly monitor Stack Overflow you will probably + receive the fastest response to your questions there. +- For AMP on Google Search questions or issues, please use + [Google's AMP forum](https://goo.gl/utQ1KZ). +- To check the status of AMP serving and its related services, see the + [AMP Status](https://status.ampproject.org/) page. **Found a bug? Suggest a feature?** -If you encounter a bug in AMP or have a feature request for AMP, see [Reporting issues with AMP](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md#reporting-issues-with-amp) for information on filing an issue or requesting features. +If you encounter a bug in AMP or have a feature request for AMP, see +[Reporting issues with AMP](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md#reporting-issues-with-amp) +for information on filing an issue or requesting features. **Contributing to AMP?** -[Contributing to AMP HTML](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md#ongoing-participation) is a great place to find out how you can make contributions to the AMP open source project and how you can get help if you run into questions when contributing to AMP. +[Contributing to AMP HTML](https://github.com/ampproject/amphtml/blob/master/CONTRIBUTING.md#ongoing-participation) +is a great place to find out how you can make contributions to the AMP open +source project and how you can get help if you run into questions when +contributing to AMP. diff --git a/ads/24smi.md b/ads/24smi.md index 127d2daa36e9..51dbe05b9d21 100644 --- a/ads/24smi.md +++ b/ads/24smi.md @@ -32,7 +32,8 @@ Provides support for [24smi](https://partner.24smi.info/) widgets. ## Configuration -For details on the configuration semantics, please contact [24smi](https://partner.24smi.info). +For details on the configuration semantics, please contact +[24smi](https://partner.24smi.info). ### Required parameters diff --git a/ads/README.md b/ads/README.md index 2d5fa355b944..cd36ff5e26e3 100644 --- a/ads/README.md +++ b/ads/README.md @@ -1,6 +1,7 @@ # Integrating ad networks into AMP -This guide provides details for ad networks to create an `amp-ad` integration for their network. +This guide provides details for ad networks to create an `amp-ad` integration +for their network. **Table of contents** @@ -25,27 +26,55 @@ This guide provides details for ad networks to create an `amp-ad` integration fo ## Overview -Ads are just another external resource and must play within the same constraints placed on all resources in AMP. AMP aims to support a large subset of existing ads with little or no changes to how the integrations work. AMP's long term goal is to further improve the impact of ads on the user experience through changes across the entire vertical client side stack. Although technically feasible, do not use amp-iframe to render display ads. Using amp-iframe for display ads breaks ad clicks and prevents recording viewability information. +Ads are just another external resource and must play within the same constraints +placed on all resources in AMP. AMP aims to support a large subset of existing +ads with little or no changes to how the integrations work. AMP's long term goal +is to further improve the impact of ads on the user experience through changes +across the entire vertical client side stack. Although technically feasible, do +not use amp-iframe to render display ads. Using amp-iframe for display ads +breaks ad clicks and prevents recording viewability information. -If you are an ad technology provider looking to integrate with AMP HTML, please also check the [general 3P inclusion guidelines](../3p/README.md#ads) and [ad service integration guidelines](./_integration-guide.md). +If you are an ad technology provider looking to integrate with AMP HTML, please +also check the [general 3P inclusion guidelines](../3p/README.md#ads) and +[ad service integration guidelines](./_integration-guide.md). ## Constraints -Below is a summary of constraints placed on external resources, such as ads in AMP HTML: - -- Because AMP pages are served on HTTPS and ads cannot be proxied, ads must be served over HTTPS. -- The size of an ad unit must be static. It must be knowable without fetching the ad and it cannot change at runtime except through [iframe resizing](#ad-resizing). -- If placing the ad requires running JavaScript (assumed to be true for 100% of ads served through networks), the ad must be placed on an origin different from the AMP document itself. Reasons include: +Below is a summary of constraints placed on external resources, such as ads in +AMP HTML: + +- Because AMP pages are served on HTTPS and ads cannot be proxied, ads must be + served over HTTPS. +- The size of an ad unit must be static. It must be knowable without fetching + the ad and it cannot change at runtime except through + [iframe resizing](#ad-resizing). +- If placing the ad requires running JavaScript (assumed to be true for 100% of + ads served through networks), the ad must be placed on an origin different + from the AMP document itself. Reasons include: - Improved security. - - Takes synchronous HTTP requests made by the ad out of the critical rendering path of the primary page. - - Allows browsers to run the ad in a different process from the primary page (even better security and prevents JS inside the ad to block the main page UI thread). - - Prevents ads doing less than optimal things to measure user behavior and other interference with the primary page. -- The AMP Runtime may at any moment decide that there are too many iframes on a page and that memory is low. In that case, the AMP Runtime unloads ads that were previously loaded and are no longer visible. It may later load new ads in the same slot if the user scrolls them back into view. -- The AMP Runtime may decide to set an ad that is currently not visible to `display: none` to reduce browser layout and compositing cost. + - Takes synchronous HTTP requests made by the ad out of the critical rendering + path of the primary page. + - Allows browsers to run the ad in a different process from the primary page + (even better security and prevents JS inside the ad to block the main page + UI thread). + - Prevents ads doing less than optimal things to measure user behavior and + other interference with the primary page. +- The AMP Runtime may at any moment decide that there are too many iframes on a + page and that memory is low. In that case, the AMP Runtime unloads ads that + were previously loaded and are no longer visible. It may later load new ads in + the same slot if the user scrolls them back into view. +- The AMP Runtime may decide to set an ad that is currently not visible to + `display: none` to reduce browser layout and compositing cost. ## The iframe sandbox -The ad itself is hosted within a document that has an origin different from the primary page. By default, the iframe loads a [bootstrap HTML](../3p/frame.max.html), which provides a container `div` to hold your content together with a set of APIs. Note that the container `div` (with `id="c"`) is absolute positioned and takes the whole space of the iframe, so you will want to append your content as a child of the container (don't append to `body`). +The ad itself is hosted within a document that has an origin different from the +primary page. By default, the iframe loads a +[bootstrap HTML](../3p/frame.max.html), which provides a container `div` to hold +your content together with a set of APIs. Note that the container `div` (with +`id="c"`) is absolute positioned and takes the whole space of the iframe, so you +will want to append your content as a child of the container (don't append to +`body`). ### Available information to the ad @@ -83,7 +112,8 @@ The AMP runtime provides the following information to the ad:
Contains the time at which processing of the amp-ad element started.
-More information can be provided in a similar fashion if needed (Please file an issue). +More information can be provided in a similar fashion if needed (Please file an +issue). ### Available APIs @@ -100,15 +130,28 @@ More information can be provided in a similar fashion if needed (Please file an ### Exceptions to available APIs and information -Depending on the ad server / provider, some methods of rendering ads involve a second iframe inside the AMP iframe. In these cases, the iframe sandbox methods and information will be unavailable to the ad. AMP is working on a creative-level API that will enable this information to be accessible in such iframed cases, and this README will be updated when that is available. Refer to the documentation for the relevant ad servers / providers (e.g., [doubleclick.md](./google/doubleclick.md)) for more details on how to handle such cases. +Depending on the ad server / provider, some methods of rendering ads involve a +second iframe inside the AMP iframe. In these cases, the iframe sandbox methods +and information will be unavailable to the ad. AMP is working on a +creative-level API that will enable this information to be accessible in such +iframed cases, and this README will be updated when that is available. Refer to +the documentation for the relevant ad servers / providers (e.g., +[doubleclick.md](./google/doubleclick.md)) for more details on how to handle +such cases. ### Ad viewability #### Position in viewport -Ads can call the special `window.context.observeIntersection(changesCallback)`API to receive IntersectionObserver style [change records](https://github.com/w3c/IntersectionObserver/blob/master/explainer.md) of the ad's intersection with the parent viewport. +Ads can call the special +`window.context.observeIntersection(changesCallback)`API to receive +IntersectionObserver style +[change records](https://github.com/w3c/IntersectionObserver/blob/master/explainer.md) +of the ad's intersection with the parent viewport. -The API allows you to specify a callback that fires with change records when AMP observes that an ad becomes visible and then while it is visible, changes are reported as they happen. +The API allows you to specify a callback that fires with change records when AMP +observes that an ad becomes visible and then while it is visible, changes are +reported as they happen. _Example usage_: @@ -120,7 +163,8 @@ window.context.observeIntersection(function(changes) { }); ``` -`window.context.observeIntersection` returns a function which when called will stop listening for intersection messages. +`window.context.observeIntersection` returns a function which when called will +stop listening for intersection messages. _Example usage_ @@ -137,34 +181,47 @@ unlisten(); ##### Initial layout rect -The value `window.context.initialLayoutRect` contains the initial rect of the ad's position in the page. +The value `window.context.initialLayoutRect` contains the initial rect of the +ad's position in the page. ##### Initial viewport intersection -The value `window.context.initialIntersection` contains the initial viewport intersection record at the time the iframe was created. +The value `window.context.initialIntersection` contains the initial viewport +intersection record at the time the iframe was created. #### Page visibility -AMP documents may be practically invisible without the visibility being reflected by the [page visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API). This is primarily the case when a document is swiped away or being prerendered. +AMP documents may be practically invisible without the visibility being +reflected by the +[page visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API). +This is primarily the case when a document is swiped away or being prerendered. Whether a document is actually being visible can be queried using: -`window.context.hidden` which is true if the page is not visible as per page visibility API or because the AMP viewer currently does not show it. +`window.context.hidden` which is true if the page is not visible as per page +visibility API or because the AMP viewer currently does not show it. -Additionally, one can observe the `amp:visibilitychange` on the `window` object to be notified about changes in visibility. +Additionally, one can observe the `amp:visibilitychange` on the `window` object +to be notified about changes in visibility. ### Ad resizing Ads can call the special API -`window.context.requestResize(width, height, opt_hasOverflow)` to send a resize request. +`window.context.requestResize(width, height, opt_hasOverflow)` to send a resize +request. -Once the request is processed the AMP runtime will try to accommodate this request as soon as -possible, but it will take into account where the reader is currently reading, whether the scrolling -is ongoing and any other UX or performance factors. +Once the request is processed the AMP runtime will try to accommodate this +request as soon as possible, but it will take into account where the reader is +currently reading, whether the scrolling is ongoing and any other UX or +performance factors. -Ads can observe whether resize request were successful using the `window.context.onResizeSuccess` and `window.context.onResizeDenied` methods. +Ads can observe whether resize request were successful using the +`window.context.onResizeSuccess` and `window.context.onResizeDenied` methods. -The `opt_hasOverflow` is an optional boolean value, ads can specify `opt_hasOverflow` to `true` to let AMP runtime know that the ad context can handle overflow when attempt to resize is denied, and not to throw warning in such cases. +The `opt_hasOverflow` is an optional boolean value, ads can specify +`opt_hasOverflow` to `true` to let AMP runtime know that the ad context can +handle overflow when attempt to resize is denied, and not to throw warning in +such cases. _Example:_ @@ -193,11 +250,14 @@ Here are some factors that affect whether the resize will be executed: - Whether the resize is triggered by the user action; - Whether the resize is requested for a currently active ad; -- Whether the resize is requested for an ad below the viewport or above the viewport. +- Whether the resize is requested for an ad below the viewport or above the + viewport. #### Specifying an overflow element -You can specify an `overflow` element that is only shown when a resize request is declined. When the user clicks the overflow element, the resize passes the "interaction" rule and will resize. +You can specify an `overflow` element that is only shown when a resize request +is declined. When the user clicks the overflow element, the resize passes the +"interaction" rule and will resize. _Example: Using an `overflow` element_ @@ -210,11 +270,17 @@ _Example: Using an `overflow` element_ ### Support for multi-size ad requests -Allowing more than a single ad size to fill a slot improves ad server competition. Increased competition gives the publisher better monetization for the same slot, therefore increasing overall revenue earned by the publisher. +Allowing more than a single ad size to fill a slot improves ad server +competition. Increased competition gives the publisher better monetization for +the same slot, therefore increasing overall revenue earned by the publisher. -To support multi-size ad requests, AMP accepts an optional `data` param to `window.context.renderStart` (details in [Available APIs](#available-apis) section) which will automatically invoke request resize with the width and height passed. +To support multi-size ad requests, AMP accepts an optional `data` param to +`window.context.renderStart` (details in [Available APIs](#available-apis) +section) which will automatically invoke request resize with the width and +height passed. -In case the resize is not successful, AMP will horizontally and vertically center align the creative within the space initially reserved for the creative. +In case the resize is not successful, AMP will horizontally and vertically +center align the creative within the space initially reserved for the creative. _Example:_ @@ -223,17 +289,24 @@ _Example:_ window.context.renderStart({width: 200, height: 100}); ``` -Note that if the creative needs to resize on user interaction, the creative can continue to do that by calling the `window.context.requestResize(width, height, opt_hasOverflow)` API. Details in [Ad Resizing](#ad-resizing). +Note that if the creative needs to resize on user interaction, the creative can +continue to do that by calling the +`window.context.requestResize(width, height, opt_hasOverflow)` API. Details in +[Ad Resizing](#ad-resizing). ### amp-consent integration -If [amp-consent](https://github.com/ampproject/amphtml/blob/master/extensions/amp-consent/amp-consent.md) extension is used on the page, `data-block-on-consent` attribute -can be added to `amp-ad` element to respect the corresponding `amp-consent` policy. -In that case, the `amp-ad` element will be blocked from loading until the consent accepted. -Individual ad network can override this default consent handling by putting a `consentHandlingOverride: true` in `ads/_config.js`. -Doing so will unblock the ad loading once the consent is responded. It will be then the ad network's responsibility -to respect user's consent choice, for example to serve non-personalized ads on consent rejection. -AMP runtime provides the following `window.context` APIs for ad network to access the consent state. +If +[amp-consent](https://github.com/ampproject/amphtml/blob/master/extensions/amp-consent/amp-consent.md) +extension is used on the page, `data-block-on-consent` attribute can be added to +`amp-ad` element to respect the corresponding `amp-consent` policy. In that +case, the `amp-ad` element will be blocked from loading until the consent +accepted. Individual ad network can override this default consent handling by +putting a `consentHandlingOverride: true` in `ads/_config.js`. Doing so will +unblock the ad loading once the consent is responded. It will be then the ad +network's responsibility to respect user's consent choice, for example to serve +non-personalized ads on consent rejection. AMP runtime provides the following +`window.context` APIs for ad network to access the consent state.
window.context.initialConsentState
-After overriding the default consent handling behavior, don't forget to update your publisher facing -documentation with the new behaviors on user's consent choices. You can refer to our documentation example [here](https://github.com/ampproject/amphtml/blob/master/ads/_ping_.md#user-consent-integration). +After overriding the default consent handling behavior, don't forget to update +your publisher facing documentation with the new behaviors on user's consent +choices. You can refer to our documentation example +[here](https://github.com/ampproject/amphtml/blob/master/ads/_ping_.md#user-consent-integration). ### Optimizing ad performance #### JS reuse across iframes -To allow ads to bundle HTTP requests across multiple ad units on the same page the object `window.context.master` will contain the window object of the iframe being elected master iframe for the current page. The `window.context.isMaster` property is `true` when the current frame is the master frame. +To allow ads to bundle HTTP requests across multiple ad units on the same page +the object `window.context.master` will contain the window object of the iframe +being elected master iframe for the current page. The `window.context.isMaster` +property is `true` when the current frame is the master frame. -The `computeInMasterFrame` function is designed to make it easy to perform a task only in the master frame and provide the result to all frames. It is also available to custom ad iframes as `window.context.computeInMasterFrame`. See [3p.js](https://github.com/ampproject/amphtml/blob/master/3p/3p.js) for function signature. +The `computeInMasterFrame` function is designed to make it easy to perform a +task only in the master frame and provide the result to all frames. It is also +available to custom ad iframes as `window.context.computeInMasterFrame`. See +[3p.js](https://github.com/ampproject/amphtml/blob/master/3p/3p.js) for function +signature. #### Preconnect and prefetch -Add the JS URLs that an ad **always** fetches or always connects to (if you know the origin but not the path) to [\_config.js](_config.js). +Add the JS URLs that an ad **always** fetches or always connects to (if you know +the origin but not the path) to [\_config.js](_config.js). -This triggers prefetch/preconnect when the ad is first seen, so that loads are faster when they come into view. +This triggers prefetch/preconnect when the ad is first seen, so that loads are +faster when they come into view. ### Ad markup -Ads are loaded using the `` tag containing the specified `type` for the ad netowkr, and name value pairs of configuration. +Ads are loaded using the `` tag containing the specified `type` for the +ad netowkr, and name value pairs of configuration. This is an example for the A9 network: @@ -295,7 +380,8 @@ and another for DoubleClick: ``` -For ad networks that support loading via a single script tag, this form is supported: +For ad networks that support loading via a single script tag, this form is +supported: ```html ``` -Note, that the network still needs to be white-listed and provide a prefix to valid URLs. AMP may add similar support for ad networks that support loading via an iframe tag. +Note, that the network still needs to be white-listed and provide a prefix to +valid URLs. AMP may add similar support for ad networks that support loading via +an iframe tag. -Technically, the `` tag loads an iframe to a generic bootstrap URL that knows how to render the ad given the parameters to the tag. +Technically, the `` tag loads an iframe to a generic bootstrap URL that +knows how to render the ad given the parameters to the tag. ### 1st party cookies -Access to a publisher's 1st party cookies may be achieved through a custom ad bootstrap file. See ["Running ads from a custom domain"](https://amp.dev/documentation/components/amp-ad#running-ads-from-a-custom-domain) in the ad documentation for details. +Access to a publisher's 1st party cookies may be achieved through a custom ad +bootstrap file. See +["Running ads from a custom domain"](https://amp.dev/documentation/components/amp-ad#running-ads-from-a-custom-domain) +in the ad documentation for details. -If the publisher would like to add custom JavaScript in the `remote.html` file that wants to read or write to the publisher owned cookies, then the publisher needs to ensure that the `remote.html` file is hosted on a sub-domain of the publisher URL. For example, if the publisher hosts a webpage on `https://nytimes.com`, then the remote file should be hosted on something similar to `https://sub-domain.nytimes.com` for the custom JavaScript to have the ability to read or write cookies for nytimes.com. +If the publisher would like to add custom JavaScript in the `remote.html` file +that wants to read or write to the publisher owned cookies, then the publisher +needs to ensure that the `remote.html` file is hosted on a sub-domain of the +publisher URL. For example, if the publisher hosts a webpage on +`https://nytimes.com`, then the remote file should be hosted on something +similar to `https://sub-domain.nytimes.com` for the custom JavaScript to have +the ability to read or write cookies for nytimes.com. ## Developer guidelines for a pull request -Please read through [DEVELOPING.md](../contributing/DEVELOPING.md) before contributing to this code repository. +Please read through [DEVELOPING.md](../contributing/DEVELOPING.md) before +contributing to this code repository. ### Files to change -If you're adding support for a new third-party ad service, changes to the following files are expected: +If you're adding support for a new third-party ad service, changes to the +following files are expected: -- `/ads/yournetwork.js`: Implement the main logic here. This is the code that's invoked in the third-party iframe once loaded. -- `/ads/yournetwork.md`: Documentation detailing yourr ad service for publishers to read. +- `/ads/yournetwork.js`: Implement the main logic here. This is the code that's + invoked in the third-party iframe once loaded. +- `/ads/yournetwork.md`: Documentation detailing yourr ad service for publishers + to read. - `/ads/_config.js`: Add service specific configuration here. - `/3p/integration.js`: Register your service here. - `/extensions/amp-ad/amp-ad.md`: Add a link that points to your publisher doc. -- `/examples/ads.amp.html`: Add publisher examples here. Since a real ad isn't guaranteed to fill, a consistently displayed fake ad is highly recommended here to help AMP developers confidently identify new bugs. +- `/examples/ads.amp.html`: Add publisher examples here. Since a real ad isn't + guaranteed to fill, a consistently displayed fake ad is highly recommended + here to help AMP developers confidently identify new bugs. ### Verify your examples To verify the examples that you have put in `/examples/ads.amp.html`: 1. Start a local gulp web server by running command `gulp`. -2. Visit `http://localhost:8000/examples/ads.amp.html?type=yournetwork` in your browser to make sure the examples load ads. +2. Visit `http://localhost:8000/examples/ads.amp.html?type=yournetwork` in your + browser to make sure the examples load ads. -Please consider having the example consistently load a fake ad (with ad targeting disabled). Not only will it be a more confident example for publishers to follow, but also allows the AMP team to catch any regression bug during AMP releases. +Please consider having the example consistently load a fake ad (with ad +targeting disabled). Not only will it be a more confident example for publishers +to follow, but also allows the AMP team to catch any regression bug during AMP +releases. It's encouraged that you have multiple examples to cover different use cases. -Please verify your ad is fully functioning, for example, by clicking on an ad. We have seen bugs reported for ads not being clickable, which was due to incorrectly appended content divs. +Please verify your ad is fully functioning, for example, by clicking on an ad. +We have seen bugs reported for ads not being clickable, which was due to +incorrectly appended content divs. ### Tests @@ -353,21 +463,32 @@ Please make sure your changes pass the tests: gulp unit --watch --nobuild --files=test/unit/{test-ads-config.js,test-integration.js} ``` -If you have non-trivial logic in `/ads/yournetwork.js`, adding a unit test at `/test/unit/ads/test-yournetwork.js` is highly recommended. +If you have non-trivial logic in `/ads/yournetwork.js`, adding a unit test at +`/test/unit/ads/test-yournetwork.js` is highly recommended. ### Lint and type-check -To speed up the review process, please run `gulp lint` and `gulp check-types`, then fix errors, if any, before sending out the PR. +To speed up the review process, please run `gulp lint` and `gulp check-types`, +then fix errors, if any, before sending out the PR. ### Other tips - Add **cc ampproject/wg-ads** in all pull request's descriptions. -- It's highly recommended to maintain [an integration test outside AMP repo](../3p/README.md#adding-proper-integration-tests). -- Please consider implementing the `render-start` and `no-content-available` APIs (see [Available APIs](#available-apis)), which helps AMP to provide user a much better ad loading experience. -- [CLA](../CONTRIBUTING.md#contributing-code): for anyone who has trouble to pass the automatic CLA check in a pull request, try to follow the guidelines provided by the CLA Bot. Common mistakes are: +- It's highly recommended to maintain + [an integration test outside AMP repo](../3p/README.md#adding-proper-integration-tests). +- Please consider implementing the `render-start` and `no-content-available` + APIs (see [Available APIs](#available-apis)), which helps AMP to provide user + a much better ad loading experience. +- [CLA](../CONTRIBUTING.md#contributing-code): for anyone who has trouble to + pass the automatic CLA check in a pull request, try to follow the guidelines + provided by the CLA Bot. Common mistakes are: 1. Using a different email address in the git commit. 2. Not providing the exact company name in the PR thread. ## Developer announcements for ads related API changes -For any major Ads API related changes that introduce new functionality or cause backwards compatible changes, we will notify the [amp-ads-announce@googlegroups.com](https://groups.google.com/d/forum/amp-ads-announce) at least 2 weeks in advance to make sure you have enough time to absorb those changes. +For any major Ads API related changes that introduce new functionality or cause +backwards compatible changes, we will notify the +[amp-ads-announce@googlegroups.com](https://groups.google.com/d/forum/amp-ads-announce) +at least 2 weeks in advance to make sure you have enough time to absorb those +changes. diff --git a/ads/_integration-guide.md b/ads/_integration-guide.md index a58a9031e0fd..82a110e8a92f 100644 --- a/ads/_integration-guide.md +++ b/ads/_integration-guide.md @@ -1,15 +1,23 @@ # Guidelines for Integrating with AMP -If you are an ad technology provider looking to integrate with AMP HTML, please see the guidelines below. -To ensure minimum latency and quality, please follow the instructions listed [here](../3p/README.md#ads) before submitting a pull request to the AMP open-source project. For general guidance on how to get started with contributing to AMP, please see [CONTRIBUTING.md](../CONTRIBUTING.md). +If you are an ad technology provider looking to integrate with AMP HTML, please +see the guidelines below. To ensure minimum latency and quality, please follow +the instructions listed [here](../3p/README.md#ads) before submitting a pull +request to the AMP open-source project. For general guidance on how to get +started with contributing to AMP, please see +[CONTRIBUTING.md](../CONTRIBUTING.md). ## Ad Server _Examples : DFP, A9_ -As an ad server, publishers you support include a JavaScript library provided by you and place various "ad snippets" that rely on the JavaScript library to fetch ads and render them on the publisher’s website. +As an ad server, publishers you support include a JavaScript library provided by +you and place various "ad snippets" that rely on the JavaScript library to fetch +ads and render them on the publisher’s website. -Because AMP doesn’t allow publishers to execute arbitrary JavaScript, you will need to contribute to the AMP open-source code to allow the `amp-ad` tag to request ads from your ad server. +Because AMP doesn’t allow publishers to execute arbitrary JavaScript, you will +need to contribute to the AMP open-source code to allow the `amp-ad` tag to +request ads from your ad server. For example : Amazon A9 server can be invoked by using following syntax: @@ -25,33 +33,55 @@ For example : Amazon A9 server can be invoked by using following syntax: ``` -Note that each of the attributes that follow `type` are dependent on the parameters that the Amazon’s A9 server expects in order to deliver an ad. The [a9.js](./a9.js) file shows you how the parameters are mapped to making a JavaScript call which invokes the A9 server via the `https://c.amazon-adsystem.com/aax2/assoc.js` URL. The corresponding parameters passed by the AMP ad tag are appended to the URL to return an ad. +Note that each of the attributes that follow `type` are dependent on the +parameters that the Amazon’s A9 server expects in order to deliver an ad. The +[a9.js](./a9.js) file shows you how the parameters are mapped to making a +JavaScript call which invokes the A9 server via the +`https://c.amazon-adsystem.com/aax2/assoc.js` URL. The corresponding parameters +passed by the AMP ad tag are appended to the URL to return an ad. -For details on how to integrate your ad network with AMP, see [Integrating ad networks into AMP](https://github.com/ampproject/amphtml/blob/master/ads/README.md). +For details on how to integrate your ad network with AMP, see +[Integrating ad networks into AMP](https://github.com/ampproject/amphtml/blob/master/ads/README.md). ## Supply Side Platform (SSP) or an Ad Exchange _Examples : Rubicon, Criteo OR Appnexus, Ad-Exchange_ -If you are a sell-side platform that wants to get called directly from a publisher’s webpage, you will need to follow the same directions as listed above for integrating with an Ad Server. Adding your own `type` value to the amp-ad tag allows you to distribute your tag directly to the publisher, so they can insert your tags directly into their AMP pages. +If you are a sell-side platform that wants to get called directly from a +publisher’s webpage, you will need to follow the same directions as listed above +for integrating with an Ad Server. Adding your own `type` value to the amp-ad +tag allows you to distribute your tag directly to the publisher, so they can +insert your tags directly into their AMP pages. -More commonly, SSPs work with the publisher to traffick the SSP’s ad tags in their ad server. In this case, ensure that all assets being loaded by your script in the ad server’s creative are being made over HTTPS. There are some restrictions around some ad formats like expandables, so we recommend that you test out the most commonly delivered creative formats with your publishers. +More commonly, SSPs work with the publisher to traffick the SSP’s ad tags in +their ad server. In this case, ensure that all assets being loaded by your +script in the ad server’s creative are being made over HTTPS. There are some +restrictions around some ad formats like expandables, so we recommend that you +test out the most commonly delivered creative formats with your publishers. ## Ad Agency _Examples : Essence, Omnicom_ -Work with your publisher to ensure that the creatives you develop are AMP-compliant. Since all creatives are served into iframes whose size is determined when the ad is called, ensure that your creative doesn't try to modify the size of the iframe. +Work with your publisher to ensure that the creatives you develop are +AMP-compliant. Since all creatives are served into iframes whose size is +determined when the ad is called, ensure that your creative doesn't try to +modify the size of the iframe. Ensure that all assets that are part of the creative are requested using HTTPS. -Some ad formats are not fully supported at the moment and we recommend testing the creatives in an AMP environment. Some examples are : Rich Media Expandables, Interstitials, Page Level Ads. +Some ad formats are not fully supported at the moment and we recommend testing +the creatives in an AMP environment. Some examples are : Rich Media Expandables, +Interstitials, Page Level Ads. ## Video Player _Examples : Brightcove, Ooyala_ -A video player that works in regular HTML pages will not work in AMP and therefore a specific tag must be created that allows the AMP Runtime to load your player. -Brightcove has created a custom [amp-brightcove](https://github.com/ampproject/amphtml/blob/master/extensions/amp-brightcove/amp-brightcove.md) tag that allows media and ads to be played in AMP pages. +A video player that works in regular HTML pages will not work in AMP and +therefore a specific tag must be created that allows the AMP Runtime to load +your player. Brightcove has created a custom +[amp-brightcove](https://github.com/ampproject/amphtml/blob/master/extensions/amp-brightcove/amp-brightcove.md) +tag that allows media and ads to be played in AMP pages. A Brightcove player can be invoked by the following: @@ -67,7 +97,8 @@ A Brightcove player can be invoked by the following: ``` -For instructions on how to develop an amp tag like Brightcove, see [this pull request](https://github.com/ampproject/amphtml/pull/1052). +For instructions on how to develop an amp tag like Brightcove, see +[this pull request](https://github.com/ampproject/amphtml/pull/1052). ## Video Ad Network @@ -82,22 +113,34 @@ If you are a video ad network, please work with your publisher to ensure that: _Examples : KRUX, Bluekai_ -See [how to enhance custom ad configuration](https://amp.dev/documentation/components/amp-ad#enhance-incoming-ad-configuration). +See +[how to enhance custom ad configuration](https://amp.dev/documentation/components/amp-ad#enhance-incoming-ad-configuration). -You can use a similar approach to enrich the ad call by passing in audience segments that you get from the user cookie into the ad call. +You can use a similar approach to enrich the ad call by passing in audience +segments that you get from the user cookie into the ad call. ## Viewability Provider _Examples : MOAT, Integral Ad Science_ -Viewability providers typically integrate with publishers via the ad server’s creative wrappers. If that is the case, ensure that the creative wrapper loads all assets over HTTPS. +Viewability providers typically integrate with publishers via the ad server’s +creative wrappers. If that is the case, ensure that the creative wrapper loads +all assets over HTTPS. -For e.g. for MOAT, make sure `http://js.moatads.com` is switched to `https://z.moatads.com` +For e.g. for MOAT, make sure `http://js.moatads.com` is switched to +`https://z.moatads.com` -Also, see the approach to using the [intersection observer pattern](https://github.com/ampproject/amphtml/blob/master/ads/README.md#ad-viewability). +Also, see the approach to using the +[intersection observer pattern](https://github.com/ampproject/amphtml/blob/master/ads/README.md#ad-viewability). ## Content-Recommendation Platform _Examples : Taboola, Outbrain_ -Useful if you have some piece of JavaScript embeded on the publisher website today but the approach will not work in AMP pages. If you would like to recommend content on an AMP page, we suggest that you use the [`amp-embed` extension](https://amp.dev/documentation/components/amp-ad) to request the content details. Please see the [Taboola](https://github.com/ampproject/amphtml/blob/master/ads/taboola.md) example. +Useful if you have some piece of JavaScript embeded on the publisher website +today but the approach will not work in AMP pages. If you would like to +recommend content on an AMP page, we suggest that you use the +[`amp-embed` extension](https://amp.dev/documentation/components/amp-ad) to +request the content details. Please see the +[Taboola](https://github.com/ampproject/amphtml/blob/master/ads/taboola.md) +example. diff --git a/ads/_ping_.md b/ads/_ping_.md index 323b328fb1aa..01c77f6abdf7 100644 --- a/ads/_ping_.md +++ b/ads/_ping_.md @@ -34,7 +34,8 @@ A fake ad type that is only used for local development. ## Configuration -For details on the configuration semantics, please contact the [ad network](#configuration) or refer to their [documentation](#ping). +For details on the configuration semantics, please contact the +[ad network](#configuration) or refer to their [documentation](#ping). ### Required parameters @@ -49,9 +50,12 @@ For details on the configuration semantics, please contact the [ad network](#con ## User Consent Integration -When [user consent](https://github.com/ampproject/amphtml/blob/master/extensions/amp-consent/amp-consent.md#blocking-behaviors) is required. \_Ping\_ ad approaches user consent in the following ways: +When +[user consent](https://github.com/ampproject/amphtml/blob/master/extensions/amp-consent/amp-consent.md#blocking-behaviors) +is required. \_Ping\_ ad approaches user consent in the following ways: - `CONSENT_POLICY_STATE.SUFFICIENT`: Serve a personalized ad to the user. - `CONSENT_POLICY_STATE.INSUFFICIENT`: Serve a non-personalized ad to the user. -- `CONSENT_POLICY_STATE.UNKNOWN_NOT_REQUIRED`: Serve a personalized ad to the user. +- `CONSENT_POLICY_STATE.UNKNOWN_NOT_REQUIRED`: Serve a personalized ad to the + user. - `CONSENT_POLICY_STATE.UNKNOWN`: Will not serve an ad to the user. diff --git a/ads/a8.md b/ads/a8.md index 9c3840ed3cce..84d63a30ce52 100644 --- a/ads/a8.md +++ b/ads/a8.md @@ -39,7 +39,8 @@ Serves ads from [a8.net](https://www.a8.net/). ## Configuration -For configuration details and to generate your tags, please contact https://support.a8.net/as/contact/form/conentry.php. +For configuration details and to generate your tags, please contact +https://support.a8.net/as/contact/form/conentry.php. ### Required parameters diff --git a/ads/a9.md b/ads/a9.md index 620cadce9c7d..ac7b85f507bd 100644 --- a/ads/a9.md +++ b/ads/a9.md @@ -16,7 +16,9 @@ limitations under the License. # A9 -The A9 amp ad unit supports the Search, Recommendation and Custom ad widgets of the Native Shopping Ads program. These widgets would need to be created here first `https://affiliate-program.amazon.com/home/ads` +The A9 amp ad unit supports the Search, Recommendation and Custom ad widgets of +the Native Shopping Ads program. These widgets would need to be created here +first `https://affiliate-program.amazon.com/home/ads` # Examples @@ -102,16 +104,24 @@ The A9 amp ad unit supports the Search, Recommendation and Custom ad widgets of ## Required parameters -- `data-amzn_assoc_ad_mode` - specify the ad type as search, manual or auto (for recommendation ads) +- `data-amzn_assoc_ad_mode` - specify the ad type as search, manual or auto (for + recommendation ads) ## Optional parameters -We have default `regionurl` as `//z-na.amazon-adsystem.com/widgets/onejs?MarketPlace=US` but this can be custom provided. The parameters `amzn_assoc_width, amzn_assoc_height, amzn_assoc_size` have been replaced as AMP provide custom setting of height and width (as specified above in the amp-ad node). For recommendation, we have `recomtype` specifying it is async or sync. +We have default `regionurl` as +`//z-na.amazon-adsystem.com/widgets/onejs?MarketPlace=US` but this can be custom +provided. The parameters `amzn_assoc_width, amzn_assoc_height, amzn_assoc_size` +have been replaced as AMP provide custom setting of height and width (as +specified above in the amp-ad node). For recommendation, we have `recomtype` +specifying it is async or sync. -All other configurations supported by the NSA ads would be supported here and would depend on the ad mode. The ad parameters need to be prefixed with "data-" +All other configurations supported by the NSA ads would be supported here and +would depend on the ad mode. The ad parameters need to be prefixed with "data-" # Support -For further queries, please feel free to reach out to your contact at Amazon Affiliates. +For further queries, please feel free to reach out to your contact at Amazon +Affiliates. Otherwise you can write to our support team: Email: nsasupport@amazon.com diff --git a/ads/accesstrade.md b/ads/accesstrade.md index 49b14adcafdd..74f00952f34a 100644 --- a/ads/accesstrade.md +++ b/ads/accesstrade.md @@ -31,7 +31,8 @@ limitations under the License. ## Configuration -For configuration details and to generate your tags, please contact https://member.accesstrade.net/atv3/contact.html. +For configuration details and to generate your tags, please contact +https://member.accesstrade.net/atv3/contact.html. Supported parameters: diff --git a/ads/adagio.md b/ads/adagio.md index 46a90b589a65..4069426df985 100755 --- a/ads/adagio.md +++ b/ads/adagio.md @@ -33,7 +33,8 @@ limitations under the License. ## Configuration -For details on the configuration semantics, please contact the ad network or refer to their documentation. +For details on the configuration semantics, please contact the ad network or +refer to their documentation. Supported parameters: diff --git a/ads/adblade.md b/ads/adblade.md index 093cb27c4be3..937e37d7b29c 100644 --- a/ads/adblade.md +++ b/ads/adblade.md @@ -32,7 +32,8 @@ limitations under the License. ## Configuration -For semantics of configuration, see [Adblade's documentation](https://www.adblade.com/doc/publisher-solutions). +For semantics of configuration, see +[Adblade's documentation](https://www.adblade.com/doc/publisher-solutions). Supported parameters: diff --git a/ads/adbutler.md b/ads/adbutler.md index 889c1fcc388b..65f5e5eb5c28 100644 --- a/ads/adbutler.md +++ b/ads/adbutler.md @@ -33,7 +33,8 @@ Serves ads from [AdButler](https://www.adbutler.com/). ## Configuration -For details on the configuration semantics, please see [AdButler's documentation](http://www.adbutlerhelp.com/amp-configuration). +For details on the configuration semantics, please see +[AdButler's documentation](http://www.adbutlerhelp.com/amp-configuration). ### Required parameters diff --git a/ads/adform.md b/ads/adform.md index 503c2fe76f60..1dfa4739668d 100644 --- a/ads/adform.md +++ b/ads/adform.md @@ -53,5 +53,5 @@ Only one of the mentioned parameters should be used at the same time. - `data-bn` - `data-mid` -- `src`: must use https protocol and must be from one of the - allowed Adform hosts. +- `src`: must use https protocol and must be from one of the allowed Adform + hosts. diff --git a/ads/adfox.md b/ads/adfox.md index 52c279952173..ad3cb051a053 100644 --- a/ads/adfox.md +++ b/ads/adfox.md @@ -31,7 +31,8 @@ limitations under the License. ## Configuration -For details on the configuration semantics, please see [AdFox's documentation](https://specs.adfox.ru/page/254/). +For details on the configuration semantics, please see +[AdFox's documentation](https://specs.adfox.ru/page/254/). ### Required parameters diff --git a/ads/adgeneration.md b/ads/adgeneration.md index 1c23a724f6e9..de27a65bb0b3 100644 --- a/ads/adgeneration.md +++ b/ads/adgeneration.md @@ -24,7 +24,8 @@ limitations under the License. ## Configuration -For details on the configuration semantics, please see [Ad Generation's documentation](https://github.com/AdGeneration/sdk/wiki). +For details on the configuration semantics, please see +[Ad Generation's documentation](https://github.com/AdGeneration/sdk/wiki). Supported parameters: diff --git a/ads/adglare.md b/ads/adglare.md index 00c0adc62f97..8ca486fb212e 100644 --- a/ads/adglare.md +++ b/ads/adglare.md @@ -33,7 +33,8 @@ limitations under the License. ## Configuration -For more information, read AdGlare's blog article about [AMP Ad Tags](https://www.adglare.com/kb/51/amp-ad-server). +For more information, read AdGlare's blog article about +[AMP Ad Tags](https://www.adglare.com/kb/51/amp-ad-server). ### Required parameters diff --git a/ads/adhese.md b/ads/adhese.md index 6ad0020fd60b..f3f84daa84ad 100644 --- a/ads/adhese.md +++ b/ads/adhese.md @@ -55,7 +55,8 @@ Serves ads from [Adhese](https://www.adhese.com). ## Configuration -For details on the configuration semantics, see the [Adhese website](https://www.adhese.com) or contact Adhese support. +For details on the configuration semantics, see the +[Adhese website](https://www.adhese.com) or contact Adhese support. ### Required parameters diff --git a/ads/adincube.md b/ads/adincube.md index bb68deb2b32c..710570bd0ec8 100644 --- a/ads/adincube.md +++ b/ads/adincube.md @@ -16,7 +16,8 @@ limitations under the License. # AdinCube -Visit [dashboard.adincube.com](https://dashboard.adincube.com/dashboard) to create a publisher account and get access to our AMP ads. +Visit [dashboard.adincube.com](https://dashboard.adincube.com/dashboard) to +create a publisher account and get access to our AMP ads. ## Examples @@ -52,11 +53,14 @@ Uses fixed size by the given `width` and `height`. ``` -Refer to the [amp-sticky-ad](https://amp.dev/documentation/components/amp-sticky-ad) documentation to see how to implement this ad. +Refer to the +[amp-sticky-ad](https://amp.dev/documentation/components/amp-sticky-ad) +documentation to see how to implement this ad. ## Configuration -For details on the configuration semantics, please contact the ad network or refer to their documentation. +For details on the configuration semantics, please contact the ad network or +refer to their documentation. ### Required parameters diff --git a/ads/adition.md b/ads/adition.md index 35c512d42c9c..d2a0b3d6c8b0 100644 --- a/ads/adition.md +++ b/ads/adition.md @@ -16,7 +16,9 @@ limitations under the License. # ADITION technologies AG -ADITION technologies AG specializes in the development and distribution of its own ad server technology, which is called ADITION ad serving. The ADITION ad server now supports AMP. +ADITION technologies AG specializes in the development and distribution of its +own ad server technology, which is called ADITION ad serving. The ADITION ad +server now supports AMP. For more information, visit [www.adition.com](https://www.adition.com). @@ -35,7 +37,9 @@ For more information, visit [www.adition.com](https://www.adition.com). ## Configuration -For semantics of configuration and examples, sign-in and see the [ADITION documentation](https://wiki.adition.com/index.php?title=ADITION_technologies_AG:Manual/AMP) or [contact ADITION](https://www.adition.com/en/contact/). +For semantics of configuration and examples, sign-in and see the +[ADITION documentation](https://wiki.adition.com/index.php?title=ADITION_technologies_AG:Manual/AMP) +or [contact ADITION](https://www.adition.com/en/contact/). Supported parameters: diff --git a/ads/adman.md b/ads/adman.md index 8c10d8dd2f44..52b13c54c4d9 100644 --- a/ads/adman.md +++ b/ads/adman.md @@ -32,7 +32,8 @@ limitations under the License. ## Configuration -For details on the configuration semantics, please see [Adman documentation](http://www.adman.gr/docs). +For details on the configuration semantics, please see +[Adman documentation](http://www.adman.gr/docs). ### Required parameters diff --git a/ads/admanmedia.md b/ads/admanmedia.md index d26f501172a1..aa5e800c1048 100644 --- a/ads/admanmedia.md +++ b/ads/admanmedia.md @@ -26,7 +26,8 @@ Please visit [www.admanmedia.com](http://www.admanmedia.com) for more details. ## Configuration -For details on the configuration semantics, see [Admanmedia documentation](http://www.admanmedia.com). +For details on the configuration semantics, see +[Admanmedia documentation](http://www.admanmedia.com). ### Required parameters diff --git a/ads/admixer.md b/ads/admixer.md index 33a845761a5a..fde8ecaedff2 100644 --- a/ads/admixer.md +++ b/ads/admixer.md @@ -31,7 +31,8 @@ limitations under the License. ## Configuration -For configuration semantics, see [Admixer documentation](http://docs.admixer.net/3/en/topic/amp-configuration). +For configuration semantics, see +[Admixer documentation](http://docs.admixer.net/3/en/topic/amp-configuration). ### Required parameters diff --git a/ads/adocean.md b/ads/adocean.md index 7c2ea4ea4145..3ea1950265bc 100644 --- a/ads/adocean.md +++ b/ads/adocean.md @@ -60,11 +60,14 @@ limitations under the License. ``` -Do not define different values for slaves within one master for paramerters: data-ao-keys, data-ao-vars and data-block-on-consent. Otherwise, the behavior will be non-deterministic. +Do not define different values for slaves within one master for paramerters: +data-ao-keys, data-ao-vars and data-block-on-consent. Otherwise, the behavior +will be non-deterministic. ## Configuration -For details on the configuration semantics, see [AdOcean documentation](http://www.adocean-global.com). +For details on the configuration semantics, see +[AdOcean documentation](http://www.adocean-global.com). ### Required parameters @@ -75,16 +78,21 @@ For details on the configuration semantics, see [AdOcean documentation](http://w - `data-ao-mode` - sync|buffered - processing mode - `data-ao-preview` - livepreview configuration id -- `data-ao-keys` - additional configuration, see adserver documentation, do not define different values for slaves within one master -- `data-ao-vars` - additional configuration, see adserver documentation, do not define different values for slaves within one master +- `data-ao-keys` - additional configuration, see adserver documentation, do not + define different values for slaves within one master +- `data-ao-vars` - additional configuration, see adserver documentation, do not + define different values for slaves within one master - `data-ao-clusters` - additional configuration,see adserver documentation - `data-ao-master` - unique id of master placement ## User Consent Integration -When [user consent](https://github.com/ampproject/amphtml/blob/master/extensions/amp-consent/amp-consent.md#blocking-behaviors) is required. AdOcean ad approaches user consent in the following ways: +When +[user consent](https://github.com/ampproject/amphtml/blob/master/extensions/amp-consent/amp-consent.md#blocking-behaviors) +is required. AdOcean ad approaches user consent in the following ways: - `CONSENT_POLICY_STATE.SUFFICIENT`: Serve a personalized ad to the user. - `CONSENT_POLICY_STATE.INSUFFICIENT`: Serve a non-personalized ad to the user. -- `CONSENT_POLICY_STATE.UNKNOWN_NOT_REQUIRED`: Serve a personalized ad to the user. +- `CONSENT_POLICY_STATE.UNKNOWN_NOT_REQUIRED`: Serve a personalized ad to the + user. - `CONSENT_POLICY_STATE.UNKNOWN`: Serve a non-personalized ad to the user. diff --git a/ads/adop.md b/ads/adop.md index 15bfac291b9d..3c0cbffd2d77 100755 --- a/ads/adop.md +++ b/ads/adop.md @@ -32,7 +32,8 @@ limitations under the License. ## Configuration -For configuration details and to generate your tags, please contact http://adop.cc +For configuration details and to generate your tags, please contact +http://adop.cc ### Required parameters diff --git a/ads/adpicker.md b/ads/adpicker.md index affb6376affa..32ae54b0fbf8 100644 --- a/ads/adpicker.md +++ b/ads/adpicker.md @@ -25,7 +25,8 @@ limitations under the License. ## Configuration -For details on the configuration semantics, visit [adpicker.net](https://adpicker.net). +For details on the configuration semantics, visit +[adpicker.net](https://adpicker.net). ### Required parameters diff --git a/ads/adplugg.md b/ads/adplugg.md index ea46980d0d63..3e208ecd5e3c 100644 --- a/ads/adplugg.md +++ b/ads/adplugg.md @@ -31,7 +31,8 @@ limitations under the License. ## Configuration -For additional info, see AdPlugg's [AMP Ad Help](https://www.adplugg.com/support/help/amp-ads). +For additional info, see AdPlugg's +[AMP Ad Help](https://www.adplugg.com/support/help/amp-ads). ### Required parameters diff --git a/ads/adreactor.md b/ads/adreactor.md index a8626f0971d8..c66666055b28 100644 --- a/ads/adreactor.md +++ b/ads/adreactor.md @@ -32,7 +32,8 @@ limitations under the License. ## Configuration -For details on the configuration semantics, please contact the ad network or refer to their documentation. +For details on the configuration semantics, please contact the ad network or +refer to their documentation. Supported parameters: diff --git a/ads/adsensor.md b/ads/adsensor.md index 1d2812d2f8be..da738d5a6dba 100644 --- a/ads/adsensor.md +++ b/ads/adsensor.md @@ -33,7 +33,8 @@ limitations under the License. ## Configuration -For details on the configuration semantics, please contact the AdSensor support team via e-mail: support@adsensor.com. +For details on the configuration semantics, please contact the AdSensor support +team via e-mail: support@adsensor.com. ## Supported parameters diff --git a/ads/adsnative.md b/ads/adsnative.md index 7a0949578af1..7973c1f5f919 100644 --- a/ads/adsnative.md +++ b/ads/adsnative.md @@ -25,7 +25,8 @@ limitations under the License. ## Configuration -For configuration details, see [AdsNative's documentation](http://dev.adsnative.com). +For configuration details, see +[AdsNative's documentation](http://dev.adsnative.com). ### Required parameters @@ -41,4 +42,5 @@ For configuration details, see [AdsNative's documentation](http://dev.adsnative. - `data-anwid`: the widget id - `data-antid`: the template id - `data-ancat`: a comma separated list of categories -- `data-ankv`: a list of key value pairs in the format `"key1:value1, key2:value2"`. +- `data-ankv`: a list of key value pairs in the format + `"key1:value1, key2:value2"`. diff --git a/ads/adspeed.md b/ads/adspeed.md index ae893273a6e3..52a8db9784dd 100644 --- a/ads/adspeed.md +++ b/ads/adspeed.md @@ -33,7 +33,8 @@ limitations under the License. ## Configuration -For configuration semantics, please see [AdSpeed documentation](https://www.adspeed.com/Knowledges/1950/Ad-Tag/Accelerated-Mobile-Pages-Project-AMP-Ad.html). +For configuration semantics, please see +[AdSpeed documentation](https://www.adspeed.com/Knowledges/1950/Ad-Tag/Accelerated-Mobile-Pages-Project-AMP-Ad.html). Supported parameters: diff --git a/ads/adspirit.md b/ads/adspirit.md index 823f9ee9817e..9a46ab2da8b7 100644 --- a/ads/adspirit.md +++ b/ads/adspirit.md @@ -31,7 +31,8 @@ limitations under the License. ## Configuration -For details on the configuration semantics, please see [AdSpirit's documentation](http://help.adspirit.de/help/). +For details on the configuration semantics, please see +[AdSpirit's documentation](http://help.adspirit.de/help/). Supported parameters: diff --git a/ads/adstir.md b/ads/adstir.md index ada9514c2df9..2f9267355074 100644 --- a/ads/adstir.md +++ b/ads/adstir.md @@ -31,7 +31,9 @@ limitations under the License. ## Configuration -For configuration details and to generate your tags, please refer to [your publisher account](https://ad-stir.com/login) or [contact AdStir](https://ad-stir.com/contact). +For configuration details and to generate your tags, please refer to +[your publisher account](https://ad-stir.com/login) or +[contact AdStir](https://ad-stir.com/contact). Supported parameters: diff --git a/ads/adstyle.md b/ads/adstyle.md index 0639ab4b3898..af83f361fcc6 100644 --- a/ads/adstyle.md +++ b/ads/adstyle.md @@ -46,7 +46,8 @@ limitations under the License. ## Configuration -For details on the configuration semantics, please contact the ad network or refer to their documentation. +For details on the configuration semantics, please contact the ad network or +refer to their documentation. ### Required parameters diff --git a/ads/adtech.md b/ads/adtech.md index 2bc0f648aab4..9e2a3eadf991 100644 --- a/ads/adtech.md +++ b/ads/adtech.md @@ -31,7 +31,8 @@ limitations under the License. ## Configuration -For details on the configuration semantics, please contact the ad network or refer to their documentation. +For details on the configuration semantics, please contact the ad network or +refer to their documentation. ### Required parameters: @@ -41,15 +42,19 @@ For details on the configuration semantics, please contact the ad network or ref ### Optional parameters: - `data-atwPlId` - placement ID (instead of Magic Number) -- `data-atwOthAT` - generic var to set key/value pairs to send with the ad call; accepts multiple values in a semi-colon delimited list +- `data-atwOthAT` - generic var to set key/value pairs to send with the ad call; + accepts multiple values in a semi-colon delimited list - `data-atwCo` - override default country code - `data-atwHtNmAT` - override ad host name - `data-atwNetId` - network ID - `data-atwWidth` - ad width (use with atwHeight only if the ad is not 300x250) - `data-atwHeight`- ad height (use with atwWidth only if the ad is not 300x250) -- `data-atwSizes` - this overrides atwWidth/atwHeight; use this to create a comma-separated list of possible ad sizes +- `data-atwSizes` - this overrides atwWidth/atwHeight; use this to create a + comma-separated list of possible ad sizes - 'data-atwPolar' - set to "1" to enable Polar.me ad in the ad spot ### Direct URL call: -- `src` - Value must start with `https:` and contain `/addyn/`. This should only be used in cases where a direct ad call is being used rather than a magic number (MN). +- `src` - Value must start with `https:` and contain `/addyn/`. This should only + be used in cases where a direct ad call is being used rather than a magic + number (MN). diff --git a/ads/adthrive.md b/ads/adthrive.md index d0fb751a8ad2..de6fd773c20a 100644 --- a/ads/adthrive.md +++ b/ads/adthrive.md @@ -16,7 +16,8 @@ limitations under the License. # AdThrive -Your site must be approved and active with [AdThrive](http://www.adthrive.com) prior to use. AdThrive will install or provide specific tags for your site. +Your site must be approved and active with [AdThrive](http://www.adthrive.com) +prior to use. AdThrive will install or provide specific tags for your site. ## Examples @@ -70,4 +71,5 @@ Your site must be approved and active with [AdThrive](http://www.adthrive.com) p ### Optional parameters -`data-sizes` - Comma separated list of ad sizes this ad slot should support. The iFrame will be resized if allowed. +`data-sizes` - Comma separated list of ad sizes this ad slot should support. The +iFrame will be resized if allowed. diff --git a/ads/adunity.md b/ads/adunity.md index dac5b2f36f67..56c8fcb30684 100644 --- a/ads/adunity.md +++ b/ads/adunity.md @@ -35,16 +35,16 @@ limitations under the License. ### Required attributes -`data-au-account` - account number -`data-au-site` - site id +`data-au-account` - account number `data-au-site` - site id ### Optional attributes `data-au-section` - section of the site (i.e. hp - homepage), can be empty value -`data-au-zone` - zone id of the ad -`data-au-dual` - this is used to fetch ads for both desktop and mobile devices automatically -`data-au-isdemo` - used to fetch demo ad +`data-au-zone` - zone id of the ad `data-au-dual` - this is used to fetch ads +for both desktop and mobile devices automatically `data-au-isdemo` - used to +fetch demo ad ### Other attributes -For more information please see ad network documentation at +For more information please see ad network documentation at + diff --git a/ads/aduptech.md b/ads/aduptech.md index 0de7971cb128..6dc3d17ea1af 100644 --- a/ads/aduptech.md +++ b/ads/aduptech.md @@ -80,7 +80,8 @@ Uses available width and the given `height`. ### Responsive -Uses available space but respecting aspect ratio by given `width` and `height` (for example 10:3). +Uses available space but respecting aspect ratio by given `width` and `height` +(for example 10:3). ```html ` tags require the `width`, `height`, `layout`, `sizes` and `type="conative"` parameters. +- All CONATIVE `` tags require the `width`, `height`, `layout`, `sizes` + and `type="conative"` parameters. ```html @@ -165,35 +169,40 @@ The template can be specified outside the `amp-ad` tag for sharing. You can refe ### data-url (mandatory) This must be starting with `https://`, and it must be the address of an ad -server returning json in the format defined below. This endpoint must be available -cross-origin. (See [CORS in AMP](https://amp.dev/documentation/guides-and-tutorials/learn/amp-caches-and-cors/amp-cors-requests).) +server returning json in the format defined below. This endpoint must be +available cross-origin. (See +[CORS in AMP](https://amp.dev/documentation/guides-and-tutorials/learn/amp-caches-and-cors/amp-cors-requests).) ### data-slot (optional) On the assumption that most pages have multiple ad slots, this is passed to the -ad server to tell it which slot is being fetched. This can be any alphanumeric string. +ad server to tell it which slot is being fetched. This can be any alphanumeric +string. -If you have only a single ad for a given value of `data-url`, it's OK not to bother with -the slot id. However, do not use two ads for the same `data-url` where one has a slot id -specified and the other does not. +If you have only a single ad for a given value of `data-url`, it's OK not to +bother with the slot id. However, do not use two ads for the same `data-url` +where one has a slot id specified and the other does not. ## Ad server -The ad server will be called once for each value of `data-url` on the page: for the vast -majority of applications, all your ads will be from a single server so it will be -called only once. +The ad server will be called once for each value of `data-url` on the page: for +the vast majority of applications, all your ads will be from a single server so +it will be called only once. -A parameter like `?ampslots=1,2` will be appended to the URL specified by `data-url` in order -to specify the slots being fetched. See the examples above for details. +A parameter like `?ampslots=1,2` will be appended to the URL specified by +`data-url` in order to specify the slots being fetched. See the examples above +for details. -The ad server should return a json object containing a record for each slot in the request, keyed by the -slot id in `data-slot`. The record format is defined by your template. For the examples above, -the record contains three fields: +The ad server should return a json object containing a record for each slot in +the request, keyed by the slot id in `data-slot`. The record format is defined +by your template. For the examples above, the record contains three fields: -- src - string to go into the source parameter of the image to be displayed. This can be a - web reference (in which case it must be `https:` or a `data:` URI including the base64-encoded image. +- src - string to go into the source parameter of the image to be displayed. + This can be a web reference (in which case it must be `https:` or a `data:` + URI including the base64-encoded image. - href - URL to which the user is to be directed when he clicks on the ad -- info - A string with additional info about the ad that was served, mmaybe for use with analytics +- info - A string with additional info about the ad that was served, mmaybe for + use with analytics Here is an example response, assuming two slots named simply 1 and 2: @@ -212,7 +221,8 @@ Here is an example response, assuming two slots named simply 1 and 2: } ``` -If no slot was specified, the server returns a single template rather than an array. +If no slot was specified, the server returns a single template rather than an +array. ```json { @@ -222,7 +232,8 @@ If no slot was specified, the server returns a single template rather than an ar } ``` -The ad server must enforce [AMP CORS](https://github.com/ampproject/amphtml/blob/master/spec/amp-cors-requests.md#cors-security-in-amp). +The ad server must enforce +[AMP CORS](https://github.com/ampproject/amphtml/blob/master/spec/amp-cors-requests.md#cors-security-in-amp). Here is an example set of the relevant response headers: ```html @@ -231,10 +242,14 @@ Access-Control-Allow-Origin:https://my--ad--server-com.cdn.ampproject.org ## Analytics -To get analytics of how your ads are performing, use the [amp-analytics](https://github.com/ampproject/amphtml/blob/master/extensions/amp-analytics/amp-analytics.md) tag. +To get analytics of how your ads are performing, use the +[amp-analytics](https://github.com/ampproject/amphtml/blob/master/extensions/amp-analytics/amp-analytics.md) +tag. -Here is an example of how to make it work with Google Analytics events. Note that the variables can be set either by the code -that displays the page (as in `eventAction`) or in variables passed back by the ad server (as in `eventCategory` and `eventLabel`). +Here is an example of how to make it work with Google Analytics events. Note +that the variables can be set either by the code that displays the page (as in +`eventAction`) or in variables passed back by the ad server (as in +`eventCategory` and `eventLabel`). ```html - - + width="1280" height="960"> ### Ad server requirements #### SSL -All network communication via the AMP HTML runtime (resources or XHR) require SSL. +All network communication via the AMP HTML runtime (resources or XHR) require +SSL. #### AMPHTML ad creative signature -For the AMP runtime to know that a creative is valid [AMP](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/amp-a4a-format.md), +For the AMP runtime to know that a creative is valid +[AMP](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/amp-a4a-format.md), and thus receive preferential ad rendering, it must pass a client-side, validation check. The creative must be sent by the ad network to a validation service which verifies that the creative conforms to the @@ -93,11 +93,12 @@ this case, the ad will simply be guaranteed to render in a cross-domain iframe. _See [Figure 1 above, Part C](#detailed-design)_ -Fast Fetch requires that the ad request be sent via [XHR CORS](https://www.w3.org/TR/cors/) -as this allows for direct communication with the ad network without the -possibility of custom javascript execution (e.g. iframe or JSONP). XHR CORS -requires a preflight request where the response needs to indicate if the request -is allowed by including the following headers in the response: +Fast Fetch requires that the ad request be sent via +[XHR CORS](https://www.w3.org/TR/cors/) as this allows for direct communication +with the ad network without the possibility of custom javascript execution (e.g. +iframe or JSONP). XHR CORS requires a preflight request where the response needs +to indicate if the request is allowed by including the following headers in the +response:
Access-Control-Allow-Origin
-For details on CORS verification in AMP context, see [Verify CORS requests](https://github.com/ampproject/amphtml/blob/master/spec/amp-cors-requests.md#verify-cors-header). +For details on CORS verification in AMP context, see +[Verify CORS requests](https://github.com/ampproject/amphtml/blob/master/spec/amp-cors-requests.md#verify-cors-header). ### Creating an AMPHTML ad extension implementation -The [``](https://amp.dev/documentation/components/amp-ad) -element differentiates between different ad network implementations via the -`type` attribute. For example, the following amp-ad tag utilizes the Google Ad Manager +The [``](https://amp.dev/documentation/components/amp-ad) element +differentiates between different ad network implementations via the `type` +attribute. For example, the following amp-ad tag utilizes the Google Ad Manager ad network: ```html @@ -140,18 +142,15 @@ To create an ad network implementation, you must perform the following: _Figure 2: File hierarchy for an AMPHTML ad implementation_ - - + width="1280" height="960"> 2. Ad networks that want to add support for Fast Fetch within AMP must add the file hierarchy to the AMP repository as show in Figure 2, with `` replaced by their own network. Files must implement all requirements as - specified below. Anything not specified, i.e. helper functions etc are at the - discretion of the ad network, but must be approved using the [process required - for all AMP contributions](https://github.com/ampproject/amphtml/blob/master/contributing/contributing-code.md). + specified below. Anything not specified, i.e. helper functions etc are at + the discretion of the ad network, but must be approved using the + [process required for all AMP contributions](https://github.com/ampproject/amphtml/blob/master/contributing/contributing-code.md). #### Create the implementation script @@ -159,7 +158,8 @@ _For reference, see [Figure 1 Parts B and D](#detailed-design)._ 1. Create a file named `amp-ad-network--impl.js`, which implement the `AmpAdNetworkImpl` class. -2. This class must extend [AmpA4A](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/0.1/amp-a4a.js). +2. This class must extend + [AmpA4A](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/0.1/amp-a4a.js). 3. This class must overwrite the super class method **getAdUrl()**. ```javascript @@ -167,7 +167,10 @@ _For reference, see [Figure 1 Parts B and D](#detailed-design)._ // @return {string} - the ad url ``` -Examples of network implementations can be seen for [Google Ad Manager](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-doubleclick-impl/0.1/amp-ad-network-doubleclick-impl.js) and [AdSense](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-adsense-impl/0.1/amp-ad-network-adsense-impl.js). +Examples of network implementations can be seen for +[Google Ad Manager](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-doubleclick-impl/0.1/amp-ad-network-doubleclick-impl.js) +and +[AdSense](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-adsense-impl/0.1/amp-ad-network-adsense-impl.js). Usage of `getAdUrl` can be seen within the `this.adPromise_ promise` chain in [amp-a4a.js](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/0.1/amp-a4a.js). @@ -185,7 +188,8 @@ _For reference, see [Figure 1: Part A](#figure-1-fast-fetch-rendering-flow)_. // @return (boolean) Whether or not A4A should be used in this context. ``` -2. Once this file is implemented, you must also update [amphtml/ads/\_a4a-config.js](https://github.com/ampproject/amphtml/blob/master/ads/_a4a-config.js). +2. Once this file is implemented, you must also update + [amphtml/ads/\_a4a-config.js](https://github.com/ampproject/amphtml/blob/master/ads/_a4a-config.js). Specifically, `IsA4AEnabled()` must be imported, and it must be mapped to the ad network type in the a4aRegistry mapping. @@ -203,16 +207,20 @@ _For reference, see [Figure 1: Part A](#figure-1-fast-fetch-rendering-flow)_. }); ``` -Example configs: [AdSense](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-adsense-impl/0.1/adsense-a4a-config.js#L68). -Usage of Google Ad Manager and AdSense configs can be seen in [\_a4a-config.js](https://github.com/ampproject/amphtml/blob/master/ads/_a4a-config.js). +Example configs: +[AdSense](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-adsense-impl/0.1/adsense-a4a-config.js#L68). +Usage of Google Ad Manager and AdSense configs can be seen in +[\_a4a-config.js](https://github.com/ampproject/amphtml/blob/master/ads/_a4a-config.js). #### Create documentation Create a file named `amp-ad-network--impl-internal.md`, and within this file provide thorough documentation for the use of your implementation. -Examples: See [Google Ad Manager](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-doubleclick-impl/amp-ad-network-doubleclick-impl-internal.md) -and [AdSense](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-adsense-impl/amp-ad-network-adsense-impl-internal.md). +Examples: See +[Google Ad Manager](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-doubleclick-impl/amp-ad-network-doubleclick-impl-internal.md) +and +[AdSense](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-adsense-impl/amp-ad-network-adsense-impl-internal.md). #### Create tests diff --git a/ads/google/a4a/docs/RTBExchangeGuide.md b/ads/google/a4a/docs/RTBExchangeGuide.md index 79583abe6632..0a4f3b719a93 100644 --- a/ads/google/a4a/docs/RTBExchangeGuide.md +++ b/ads/google/a4a/docs/RTBExchangeGuide.md @@ -4,21 +4,34 @@ ## Objective -This guide is designed to provide additional information for SSPs and Ad Exchanges that want to support AMPHTML ads in a Real-Time Bidding (RTB) environment. The IAB's OpenRTB 2.5 spec is [here](http://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf). +This guide is designed to provide additional information for SSPs and Ad +Exchanges that want to support AMPHTML ads in a Real-Time Bidding (RTB) +environment. The IAB's OpenRTB 2.5 spec is +[here](http://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf). -AMP pages must ensure all content conforms to the AMP format. When non-AMP content is included in an AMP page, there can be a delay as the content is verified. A major benefit for AMPHTML ads on AMP pages is that the ad can be rendered early by splicing the ad into the surrounding AMP page, without affecting the UX of the page and without delay. +AMP pages must ensure all content conforms to the AMP format. When non-AMP +content is included in an AMP page, there can be a delay as the content is +verified. A major benefit for AMPHTML ads on AMP pages is that the ad can be +rendered early by splicing the ad into the surrounding AMP page, without +affecting the UX of the page and without delay. -For those new to AMPHTML ads, see the background docs at the bottom of this article. +For those new to AMPHTML ads, see the background docs at the bottom of this +article. ## AMPHTML Ads in RTB: High-Level Approach ### RTB Bid Request -Exchanges will need to indicate in the RTB bid request whether a page is built in AMP, and any specific requirements or treatment of AMPHTML ads. As of [OpenRTB 2.5](http://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf), this is not yet included in the spec, but the proposed implementation to the IAB committee is as follows. +Exchanges will need to indicate in the RTB bid request whether a page is built +in AMP, and any specific requirements or treatment of AMPHTML ads. As of +[OpenRTB 2.5](http://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf), +this is not yet included in the spec, but the proposed implementation to the IAB +committee is as follows. **`Site` Object additional field: `amp`** -A new field is added to the `Site` object of the OpenRTB standard to indicate whether a webpage is built on AMP. In OpenRTB 2.5, this is section 3.2.13. +A new field is added to the `Site` object of the OpenRTB standard to indicate +whether a webpage is built on AMP. In OpenRTB 2.5, this is section 3.2.13. | Field | Scope | Type | Default | Description | | ----- | -------- | ------- | :-----: | ------------------------------------------------------------------------------------------------------------------------------------------- | @@ -26,7 +39,9 @@ A new field is added to the `Site` object of the OpenRTB standard to indicate wh **`Imp` Object additional field: `ampad`** -A new field is added to the `Imp` object of the OpenRTB standard to provide more detail around AMP ad requirements and how AMP ads will load. In OpenRTB 2.5, this is section 3.2.4. +A new field is added to the `Imp` object of the OpenRTB standard to provide more +detail around AMP ad requirements and how AMP ads will load. In OpenRTB 2.5, +this is section 3.2.4. | Field | Scope | Type | Default | Description | | ------- | -------- | ------- | :-----: | ---------------------------------------------------------------------------- | @@ -45,7 +60,12 @@ A new field is added to the `Imp` object of the OpenRTB standard to provide more ### RTB Bid Response -SSPs will need to provide a new field in the bid response to allow bidders to return AMPHTML content, and RTB bidders will need to populate that field in order to return AMPHTML ads. As of [OpenRTB 2.5](http://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf), this is not yet included in the spec, but the proposed workflow is a new field that accepts a URL pointing to AMP ad content. +SSPs will need to provide a new field in the bid response to allow bidders to +return AMPHTML content, and RTB bidders will need to populate that field in +order to return AMPHTML ads. As of +[OpenRTB 2.5](http://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf), +this is not yet included in the spec, but the proposed workflow is a new field +that accepts a URL pointing to AMP ad content. **`Bid` Object additional field: `ampadurl`** @@ -55,22 +75,40 @@ SSPs will need to provide a new field in the bid response to allow bidders to re ### Verification of valid AMP -- For AMPHTML ads to be rendered early, the exchange is required to verify and sign in real time that the ad is written in amp4ads `` creative format. -- See "[Proposed Design](https://github.com/ampproject/amphtml/issues/3133)" for signing. -- Ads that are valid AMPHTML ads will be allowed to render early by AMP pages. Ads that are not verified as valid AMPHTML ads will render at the same speed as non-AMPHTML ads. +- For AMPHTML ads to be rendered early, the exchange is required to verify and + sign in real time that the ad is written in amp4ads `` creative + format. +- See "[Proposed Design](https://github.com/ampproject/amphtml/issues/3133)" for + signing. +- Ads that are valid AMPHTML ads will be allowed to render early by AMP pages. + Ads that are not verified as valid AMPHTML ads will render at the same speed + as non-AMPHTML ads. - Only AMPHTML ads should be returned in the `ampadurl`. ### Server-side fetch -- For AMPHTML ads to be rendered early, AMPHTML ad content must be fetched with 0 additional "hops" from the client. This is designed to avoid poor user experiences due to ad latency and extra client-side calls. -- The exchange's servers (not the client browser) will request the AMPHTML ad content located at the URL provided in `ampadurl` after a bidder wins the auction. -- Creative servers must respond and return content within some reasonable SLA, recommended at 150ms. -- The AMPHTML ad will be injected into the adslot and subsequently rendered. Note that since a valid AMPHTML ad cannot contain an iframe or another ad tag, the server-side fetch must retrieve the actual HTML of the creative. +- For AMPHTML ads to be rendered early, AMPHTML ad content must be fetched with + 0 additional "hops" from the client. This is designed to avoid poor user + experiences due to ad latency and extra client-side calls. +- The exchange's servers (not the client browser) will request the AMPHTML ad + content located at the URL provided in `ampadurl` after a bidder wins the + auction. +- Creative servers must respond and return content within some reasonable SLA, + recommended at 150ms. +- The AMPHTML ad will be injected into the adslot and subsequently rendered. + Note that since a valid AMPHTML ad cannot contain an iframe or another ad tag, + the server-side fetch must retrieve the actual HTML of the creative. ### Impression Tracking and Billing URLs -- RTB buyers often include impression trackers as a structured field in the bid response (for example `Bid.burl`, the "billing notice URL" in OpenRTB 2.5). -- It is up to the exchange or publisher ad server to determine how these URLs are fired, but <[amp-pixel](https://amp.dev/documentation/components/amp-pixel)> and <[amp-analytics](https://amp.dev/documentation/components/amp-analytics)> can handle most impression tracking and analytics use cases. +- RTB buyers often include impression trackers as a structured field in the bid + response (for example `Bid.burl`, the "billing notice URL" in OpenRTB 2.5). +- It is up to the exchange or publisher ad server to determine how these URLs + are fired, but + <[amp-pixel](https://amp.dev/documentation/components/amp-pixel)> + and + <[amp-analytics](https://amp.dev/documentation/components/amp-analytics)> + can handle most impression tracking and analytics use cases. ## Background Docs @@ -79,5 +117,8 @@ SSPs will need to provide a new field in the bid response to allow bidders to re - [AMPHTML Ads Overview (Github)](https://github.com/ampproject/amphtml/blob/master/ads/google/a4a/docs/a4a-readme.md) - [AMPHTML Ads Website from amp.dev](https://amp.dev/community/platform-and-vendor-partners) - [Example AMPHTML Ads](https://amp.dev/documentation/examples/) -- [Speed comparison](https://amp.dev/documentation/examples/advertising-analytics/amphtml_ads_vs_non_amp_ads/?format=websites): see how fast an AMP Ad loads in comparison to a regular ad. Best viewed on a 3G connection. -- [Discussion in OpenRTB Dev Forum](https://groups.google.com/forum/#!topic/openrtb-dev/0wyPsF5D07Q): RTB Specific Proposal +- [Speed comparison](https://amp.dev/documentation/examples/advertising-analytics/amphtml_ads_vs_non_amp_ads/?format=websites): + see how fast an AMP Ad loads in comparison to a regular ad. Best viewed on a + 3G connection. +- [Discussion in OpenRTB Dev Forum](https://groups.google.com/forum/#!topic/openrtb-dev/0wyPsF5D07Q): + RTB Specific Proposal diff --git a/ads/google/a4a/docs/a4a-readme.md b/ads/google/a4a/docs/a4a-readme.md index fe47824ee5ac..306eff7d9fcf 100644 --- a/ads/google/a4a/docs/a4a-readme.md +++ b/ads/google/a4a/docs/a4a-readme.md @@ -1,5 +1,7 @@ # AMPHTML ads -For details, please update your link to point to the latest doc available at: https://amp.dev/documentation/guides-and-tutorials/learn/intro-to-amphtml-ads. +For details, please update your link to point to the latest doc available at: +https://amp.dev/documentation/guides-and-tutorials/learn/intro-to-amphtml-ads. -_Need to make changes to the doc_? The doc is now hosted in the [docs repo](https://github.com/ampproject/docs/blob/master/content/docs/ads/amphtml_ads.md). +_Need to make changes to the doc_? The doc is now hosted in the +[docs repo](https://github.com/ampproject/docs/blob/master/content/docs/ads/amphtml_ads.md). diff --git a/ads/google/adsense.md b/ads/google/adsense.md index bbd997992676..248305c44882 100644 --- a/ads/google/adsense.md +++ b/ads/google/adsense.md @@ -34,7 +34,10 @@ limitations under the License. ## Configuration -For semantics of configuration, please see [ad network documentation](https://support.google.com/adsense/answer/7183212?hl=en). For AdSense for Search and AdSense for Shopping, please see the [CSA AMP ad type](https://github.com/ampproject/amphtml/blob/master/ads/google/csa.md). +For semantics of configuration, please see +[ad network documentation](https://support.google.com/adsense/answer/7183212?hl=en). +For AdSense for Search and AdSense for Shopping, please see the +[CSA AMP ad type](https://github.com/ampproject/amphtml/blob/master/ads/google/csa.md). Supported parameters: diff --git a/ads/google/csa.md b/ads/google/csa.md index 40c2d6362196..9bd26a3c7a1a 100644 --- a/ads/google/csa.md +++ b/ads/google/csa.md @@ -33,7 +33,8 @@ Javascript object you would pass in the ad request of a standard CSA request. ``` -Please see documentation for [AdSense for Search](https://developers.google.com/custom-search-ads/docs/implementation-guide) +Please see documentation for +[AdSense for Search](https://developers.google.com/custom-search-ads/docs/implementation-guide) for more information. ## AdSense For Shopping (AFSh) @@ -53,21 +54,24 @@ Javascript object you would pass in the ad request of a standard CSA request. ``` -To request an AFSh ad with a width equal to the screen width, use "auto" for -the CSA width parameter. Please note that "auto" width is not supported in -non-AMP implementations. +To request an AFSh ad with a width equal to the screen width, use "auto" for the +CSA width parameter. Please note that "auto" width is not supported in non-AMP +implementations. -Note that only the [multiple-format](https://developers.google.com/adsense-for-shopping/docs/multiplereference) AdSense for Shopping ads are supported under this integration. +Note that only the +[multiple-format](https://developers.google.com/adsense-for-shopping/docs/multiplereference) +AdSense for Shopping ads are supported under this integration. -Please see documentation for [AdSense for Shopping](https://developers.google.com/adsense-for-shopping/docs/implementation-guide) +Please see documentation for +[AdSense for Shopping](https://developers.google.com/adsense-for-shopping/docs/implementation-guide) for more information. ### AFSh with AFS Backfill To request AFS ads when AFSh does not return any ads, include both the **data-afs-\*** and **data-afsh-\*** attributes in the amp-ad tag. If AFSh does -not return ads, AMP will request AFS ads with the values from the **data-afs-\*** -attributes. +not return ads, AMP will request AFS ads with the values from the +**data-afs-\*** attributes. ```html +[filter formats="websites, stories, ads"] This attribute is similar to the `src` +attribute on the `img` tag. The value must be a URL that points to a +publicly-cacheable image file. Cache providers may rewrite these URLs when +ingesting AMP files to point to a cached version of the image. [/filter] + -[filter formats="email"] -This attribute is similar to the `src` attribute on the `img` tag. For emails, the URL must be `https`. -[/filter] +[filter formats="email"] This attribute is similar to the `src` attribute on the +`img` tag. For emails, the URL must be `https`. [/filter] + [filter formats="websites, stories, ads"] ### srcset -Same as `srcset` attribute on the `img` tag. For browsers that do not support `srcset`, `` will default to using `src`. If only `srcset` and no `src` is provided, the first url in the `srcset` will be selected. -[/filter] +Same as `srcset` attribute on the `img` tag. For browsers that do not support +`srcset`, `` will default to using `src`. If only `srcset` and no `src` +is provided, the first url in the `srcset` will be selected. [/filter] + ### sizes -The value of the AMP `sizes` attribute is a sizes expression that selects the defined size corresponding to the media query based on the current window size. Additionally, AMP sets an inline style for `width` on the element. If the `srcset` attribute is provided, `` will autogenerate the HTML5 definition of the `sizes` attribute for the underlying ``, when none is specified. If the `srcset` attribute is not provided, no `sizes` attribute will be autogenerated for the underlying ``. - -It is possible to use `sizes` on `` without `srcset` purely for setting an inline style for `width` according to the matched media query, or purely for inferencing layout `responsive`. - -{% call callout('Read on', type='read') %} -For the `` tag in `HTML`, the `sizes` attribute is used in conjunction with the `srcset` attribute and specifies the intended display size of the image as corresponding to a media condition. It will influence the intrinsic display size of the underlying `` based on [browser behavior](https://gist.github.com/cathyxz/f17d12c07d60bcef52591e64e5e684fb). +The value of the AMP `sizes` attribute is a sizes expression that selects the +defined size corresponding to the media query based on the current window size. +Additionally, AMP sets an inline style for `width` on the +element. If the `srcset` attribute is provided, `` will +autogenerate the HTML5 definition of the `sizes` attribute for the underlying +``, when none is specified. If the `srcset` attribute is not provided, no +`sizes` attribute will be autogenerated for the underlying ``. + +It is possible to use `sizes` on `` without `srcset` purely for setting +an inline style for `width` according to the matched media query, or purely for +inferencing layout `responsive`. + +{% call callout('Read on', type='read') %} For the `` tag in `HTML`, the +`sizes` attribute is used in conjunction with the `srcset` attribute and +specifies the intended display size of the image as corresponding to a media +condition. It will influence the intrinsic display size of the underlying +`` based on +[browser behavior](https://gist.github.com/cathyxz/f17d12c07d60bcef52591e64e5e684fb). {% endcall %} -See [Responsive images with srcset, sizes & heights](https://amp.dev/documentation/guides-and-tutorials/develop/style_and_layout/art_direction) for usage of `sizes` and `srcset`. +See +[Responsive images with srcset, sizes & heights](https://amp.dev/documentation/guides-and-tutorials/develop/style_and_layout/art_direction) +for usage of `sizes` and `srcset`. ### alt @@ -153,25 +189,31 @@ A string of alternate text, similar to the `alt` attribute on `img`. ### attribution -A string that indicates the attribution of the image. For example, `attribution="CC courtesy of Cats on Flicker"` +A string that indicates the attribution of the image. For example, +`attribution="CC courtesy of Cats on Flicker"` ### height and width -An explicit size of the image, which is used by the AMP runtime to determine the aspect ratio without fetching the image. +An explicit size of the image, which is used by the AMP runtime to determine the +aspect ratio without fetching the image. ### common attributes -This element includes [common attributes](https://amp.dev/documentation/guides-and-tutorials/learn/common_attributes) extended to AMP components. +This element includes +[common attributes](https://amp.dev/documentation/guides-and-tutorials/learn/common_attributes) +extended to AMP components. ### data attributes -Data attributes are copied from the `amp-img` element to the internal `img` element created by the component. +Data attributes are copied from the `amp-img` element to the internal `img` +element created by the component. [filter formats="email"] ### Invalid AMP email attributes -The AMP for Email spec disallows the use of the following attributes on the AMP email format. +The AMP for Email spec disallows the use of the following attributes on the AMP +email format. - `[src]` - `[srcset]` @@ -181,9 +223,9 @@ The AMP for Email spec disallows the use of the following attributes on the AMP - `object-fit` - `object-position` -[tip type="read-on"] -Enable a lightbox effect on `amp-img` in email by using the [`amp-image-lightbox`](../extensions/amp-image-lightbox/amp-image-lightbox.md) component with the `on` action. -[/tip][/filter] +[tip type="read-on"] Enable a lightbox effect on `amp-img` in email by using the +[`amp-image-lightbox`](../extensions/amp-image-lightbox/amp-image-lightbox.md) +component with the `on` action. [/tip][/filter] ## Styling @@ -200,14 +242,28 @@ amp-img { #### Scaling an image up to a maximum width -If you want your image to scale as the window is resized but up to a maximum width (so the image doesn't stretch beyond its width): +If you want your image to scale as the window is resized but up to a maximum +width (so the image doesn't stretch beyond its width): 1. Set `layout=responsive` for ``. -2. On the container of the image, specify the `max-width:` CSS attribute. Why on the container? An `amp-img` element with `layout=responsive` is a _block-level_ element, whereas, `` is _inline_. Alternatively, you could set `display: inline-block` in your CSS for the amp-img element. +2. On the container of the image, specify the + `max-width:` CSS attribute. Why on the container? + An `amp-img` element with `layout=responsive` is a _block-level_ element, + whereas, `` is _inline_. Alternatively, you could set + `display: inline-block` in your CSS for the amp-img element. #### The difference between responsive and intrinsic layout -Both the `responsive` and `intrinsic` layouts create an image that will scale automatically. The main difference is that the `intrinsic` layout uses an SVG image as its scaling element. This will make it behave in the same way as a standard HTML image while retaining the benefit of the browser knowing the image size on initial layout. The `intrinsic` layout will have an intrinsic size and will inflate a floated `div` until it reaches either the image size defined by the width and height attributes passed to the amp-img (not by the natural size of the image) or a CSS constraint such as `max-width`. or a CSS constraint like `max-width`. The `responsive` layout will render 0x0 in a floated `div` because it takes its size from the parent, which has no natural size when floated. +Both the `responsive` and `intrinsic` layouts create an image that will scale +automatically. The main difference is that the `intrinsic` layout uses an SVG +image as its scaling element. This will make it behave in the same way as a +standard HTML image while retaining the benefit of the browser knowing the image +size on initial layout. The `intrinsic` layout will have an intrinsic size and +will inflate a floated `div` until it reaches either the image size defined by +the width and height attributes passed to the amp-img (not by the natural size +of the image) or a CSS constraint such as `max-width`. or a CSS constraint like +`max-width`. The `responsive` layout will render 0x0 in a floated `div` because +it takes its size from the parent, which has no natural size when floated. #### Setting a fixed sized image @@ -216,15 +272,18 @@ If you want your image to display at a fixed size: 1. Set `layout=fixed` for ``. 2. Specify the `width` and `height`. -{% call callout('Read on', type='read') %} -Learn about the [inferred layout](https://amp.dev/documentation/guides-and-tutorials/develop/style_and_layout/control_layout#what-if-the-layout-attribute-isn%E2%80%99t-specified?) if you don't specify the `layout` attribute. -{% endcall %} +{% call callout('Read on', type='read') %} Learn about the +[inferred layout](https://amp.dev/documentation/guides-and-tutorials/develop/style_and_layout/control_layout#what-if-the-layout-attribute-isn%E2%80%99t-specified?) +if you don't specify the `layout` attribute. {% endcall %} #### Setting the aspect ratio -For responsive images, the `width` and `height` do not need to match the exact width and height of the `amp-img`; those values just need to result in the same aspect-ratio. +For responsive images, the `width` and `height` do not need to match the exact +width and height of the `amp-img`; those values just need to result in the same +aspect-ratio. -For example, instead of specifying `width="900"` and `height="675"`, you can just specify `width="1.33"` and `height="1"`. +For example, instead of specifying `width="900"` and `height="675"`, you can +just specify `width="1.33"` and `height="1"`. [example preview="inline" playground="true"] @@ -243,27 +302,51 @@ For example, instead of specifying `width="900"` and `height="675"`, you can jus #### Setting multiple source files for different screen resolutions -[filter formats="websites, stories, ads"] -The [`srcset`](#attributes) attribute should be used to provide different resolutions of the same image, that all have the same aspect ratio. The browser will automatically choose the most appropriate file from `srcset` based on the screen resolution and width of the user's device. - -In contrast, the [`media`](https://www.ampproject.org/docs/reference/common_attributes#media) attribute shows or hides AMP components, and should be used when designing responsive layouts. The appropriate way to display images with differing aspect ratios is to use multiple `` components, each with a `media` attribute that matches the screen widths in which to show each instance. - -See the guide on [creating responsive AMP pages](https://amp.dev/documentation/guides-and-tutorials/develop/style_and_layout/responsive_design#displaying-responsive-images) for more details. -[/filter] - -[filter formats="email"] -The [`media`](https://www.ampproject.org/docs/reference/common_attributes#media) attribute shows or hides AMP components, and should be used when designing responsive layouts. The appropriate way to display images with differing aspect ratios is to use multiple `` components, each with a `media` attribute that matches the screen widths in which to show each instance. - -See the guide on [creating responsive AMP pages](https://amp.dev/documentation/guides-and-tutorials/develop/style_and_layout/responsive_design#displaying-responsive-images) for more details. -[/filter] +[filter formats="websites, stories, ads"] The [`srcset`](#attributes) attribute +should be used to provide different resolutions of the same image, that all have +the same aspect ratio. The browser will automatically choose the most +appropriate file from `srcset` based on the screen resolution and width of the +user's device. + +In contrast, the +[`media`](https://www.ampproject.org/docs/reference/common_attributes#media) +attribute shows or hides AMP components, and should be used when designing +responsive layouts. The appropriate way to display images with differing aspect +ratios is to use multiple `` components, each with a `media` attribute +that matches the screen widths in which to show each instance. + +See the guide on +[creating responsive AMP pages](https://amp.dev/documentation/guides-and-tutorials/develop/style_and_layout/responsive_design#displaying-responsive-images) +for more details. [/filter] + +[filter formats="email"] The +[`media`](https://www.ampproject.org/docs/reference/common_attributes#media) +attribute shows or hides AMP components, and should be used when designing +responsive layouts. The appropriate way to display images with differing aspect +ratios is to use multiple `` components, each with a `media` attribute +that matches the screen widths in which to show each instance. + +See the guide on +[creating responsive AMP pages](https://amp.dev/documentation/guides-and-tutorials/develop/style_and_layout/responsive_design#displaying-responsive-images) +for more details. [/filter] [filter formats="websites, stories, ads"] #### Maintaining the aspect ratio for images with unknown dimensions -The AMP layout system requires the aspect ratio of an image in advance before fetching the image; however, in some cases you might not know the image's dimensions. To display images with unknown dimensions and maintain the aspect ratios, combine AMP's [`fill`](https://amp.dev/documentation/guides-and-tutorials/develop/style_and_layout/control_layout) layout with the [`object-fit`](https://css-tricks.com/almanac/properties/o/object-fit/) CSS property. For more information, see the [How to support images with unknown dimensions](https://amp.dev/documentation/examples/style-layout/how_to_support_images_with_unknown_dimensions/) example. -[/filter] +The AMP layout system requires the aspect ratio of an image in advance before +fetching the image; however, in some cases you might not know the image's +dimensions. To display images with unknown dimensions and maintain the aspect +ratios, combine AMP's +[`fill`](https://amp.dev/documentation/guides-and-tutorials/develop/style_and_layout/control_layout) +layout with the +[`object-fit`](https://css-tricks.com/almanac/properties/o/object-fit/) CSS +property. For more information, see the +[How to support images with unknown dimensions](https://amp.dev/documentation/examples/style-layout/how_to_support_images_with_unknown_dimensions/) +example. [/filter] ## Validation -See [amp-img rules](https://github.com/ampproject/amphtml/blob/master/validator/validator-main.protoascii) in the AMP validator specification. +See +[amp-img rules](https://github.com/ampproject/amphtml/blob/master/validator/validator-main.protoascii) +in the AMP validator specification. diff --git a/builtins/amp-layout.md b/builtins/amp-layout.md index d8cee3315253..683de2af04db 100644 --- a/builtins/amp-layout.md +++ b/builtins/amp-layout.md @@ -29,11 +29,17 @@ limitations under the License. ## Overview -The `amp-layout` component allows you to apply aspect-ratio based responsive layouts to any element. The `amp-layout` component works similarly to the [layout](https://amp.dev/documentation/guides-and-tutorials/develop/style_and_layout/control_layout#the-layout-attribute) attribute on existing AMP components, but supports any HTML markup as children. Other supported layouts all work with `amp-layout` (e.g., fixed-height, fixed, etc.). +The `amp-layout` component allows you to apply aspect-ratio based responsive +layouts to any element. The `amp-layout` component works similarly to the +[layout](https://amp.dev/documentation/guides-and-tutorials/develop/style_and_layout/control_layout#the-layout-attribute) +attribute on existing AMP components, but supports any HTML markup as children. +Other supported layouts all work with `amp-layout` (e.g., fixed-height, fixed, +etc.). **Example** -This example uses `amp-layout` to create a responsive container around a circle drawn with inline SVG. +This example uses `amp-layout` to create a responsive container around a circle +drawn with inline SVG. ```html @@ -46,8 +52,12 @@ This example uses `amp-layout` to create a responsive container around a circle ## Attributes -This element includes [common attributes](https://amp.dev/documentation/guides-and-tutorials/learn/common_attributes) extended to AMP components. +This element includes +[common attributes](https://amp.dev/documentation/guides-and-tutorials/learn/common_attributes) +extended to AMP components. ## Validation -See [amp-layout rules](https://github.com/ampproject/amphtml/blob/master/validator/validator-main.protoascii) in the AMP validator specification. +See +[amp-layout rules](https://github.com/ampproject/amphtml/blob/master/validator/validator-main.protoascii) +in the AMP validator specification. diff --git a/builtins/amp-pixel.md b/builtins/amp-pixel.md index c43b115e3ee9..6edc75b9aa61 100644 --- a/builtins/amp-pixel.md +++ b/builtins/amp-pixel.md @@ -45,16 +45,21 @@ limitations under the License. ## Behavior -The `amp-pixel` component behaves like a simple tracking pixel `img`. It takes a single URL, but provides variables that can be replaced by the component in the URL string when making the request. See the [substitutions](#substitutions) section for further details. +The `amp-pixel` component behaves like a simple tracking pixel `img`. It takes a +single URL, but provides variables that can be replaced by the component in the +URL string when making the request. See the [substitutions](#substitutions) +section for further details. -In this basic example, the `amp-pixel` issues a simple GET request to the given URL and ignores the result. +In this basic example, the `amp-pixel` issues a simple GET request to the given +URL and ignores the result. ```html ``` -{% call callout('Note', type='note') %} -When processing AMP URLs in the referrer header of analytics requests, strip out or ignore the `usqp` parameter. This parameter is used by Google to trigger experiments for the Google AMP Cache. +{% call callout('Note', type='note') %} When processing AMP URLs in the referrer +header of analytics requests, strip out or ignore the `usqp` parameter. This +parameter is used by Google to trigger experiments for the Google AMP Cache. {% endcall %} ## Attributes @@ -65,7 +70,9 @@ A simple URL to a remote endpoint that must be `https` protocol. ##### referrerpolicy (optional) -This attribute is similar to the `referrerpolicy` attribute on ``, however `no-referrer` is the only accepted value. If `referrerpolicy=no-referrer` is specified, the `referrer` header is removed from the HTTP request. +This attribute is similar to the `referrerpolicy` attribute on ``, however +`no-referrer` is the only accepted value. If `referrerpolicy=no-referrer` is +specified, the `referrer` header is removed from the HTTP request. ```html `, however ##### allow-ssr-img (optional) -This attribute used in AMP4ADS creatives indicates that as part of post validation -transformation, an img element may be placed directly within the amp-pixel -element allowing the ping to be sent in parallel with AMP runtime fetch/execution. -Note that it means that any macros within the url will NOT be expanded so only -use if they are not present in the src. +This attribute used in AMP4ADS creatives indicates that as part of post +validation transformation, an img element may be placed directly within the +amp-pixel element allowing the ping to be sent in parallel with AMP runtime +fetch/execution. Note that it means that any macros within the url will NOT be +expanded so only use if they are not present in the src. ##### common attributes -This element includes [common attributes](https://amp.dev/documentation/guides-and-tutorials/learn/common_attributes) extended to AMP components. +This element includes +[common attributes](https://amp.dev/documentation/guides-and-tutorials/learn/common_attributes) +extended to AMP components. ## Substitutions -The `amp-pixel` allows all standard URL variable substitutions. -See the [Substitutions Guide](../spec/amp-var-substitutions.md) for more information. +The `amp-pixel` allows all standard URL variable substitutions. See the +[Substitutions Guide](../spec/amp-var-substitutions.md) for more information. -In the following example, a request might be made to something like `https://foo.com/pixel?0.8390278471201` where the RANDOM value is randomly generated upon each impression. +In the following example, a request might be made to something like +`https://foo.com/pixel?0.8390278471201` where the RANDOM value is randomly +generated upon each impression. ```html @@ -104,4 +115,6 @@ In the following example, a request might be made to something like `https://foo ## Validation -See [amp-pixel rules](https://github.com/ampproject/amphtml/blob/master/validator/validator-main.protoascii) in the AMP validator specification. +See +[amp-pixel rules](https://github.com/ampproject/amphtml/blob/master/validator/validator-main.protoascii) +in the AMP validator specification. diff --git a/contributing/CODE_OWNERSHIP.md b/contributing/CODE_OWNERSHIP.md index bf201bc8bc8c..3d31fde7b211 100644 --- a/contributing/CODE_OWNERSHIP.md +++ b/contributing/CODE_OWNERSHIP.md @@ -1,9 +1,14 @@ # Code Ownership and AMP -This document describes the code ownership (OWNERS) model for the AMP open source -project. This model is used in the [amphtml repository](https://github.com/ampproject/amphtml) and may be used by other AMP repositories as well. +This document describes the code ownership (OWNERS) model for the AMP open +source project. This model is used in the +[amphtml repository](https://github.com/ampproject/amphtml) and may be used by +other AMP repositories as well. -For more information on the overall code contribution process that the OWNERS model is a part of, see the [Contributing code and features](https://github.com/ampproject/amphtml/blob/master/contributing/contributing-code.md) documentation. +For more information on the overall code contribution process that the OWNERS +model is a part of, see the +[Contributing code and features](https://github.com/ampproject/amphtml/blob/master/contributing/contributing-code.md) +documentation. The goals of enforcing AMP code ownership are as follows: @@ -60,19 +65,21 @@ An earlier version of this bot was limited by GitHub's API, which could only post comments to pull requests. This did not scale well at the time, and use of the bot was discontinued. -Today, GitHub supports a new [status API](https://developer.github.com/v3/repos/statuses/) -that will be used by the bot to directly update the status of pull requests as -described above. Stay tuned for the latest changes. +Today, GitHub supports a new +[status API](https://developer.github.com/v3/repos/statuses/) that will be used +by the bot to directly update the status of pull requests as described above. +Stay tuned for the latest changes. ## Approvals required before merging a change -Any change in AMP requires the approval of at least one owner of the code the change -modifies, but this is a subset of the required approvals before a change may be merged. -See the [code contribution process](./contributing-code.md) for more details. +Any change in AMP requires the approval of at least one owner of the code the +change modifies, but this is a subset of the required approvals before a change +may be merged. See the [code contribution process](./contributing-code.md) for +more details. ## Criteria for being listed as an owner in an `OWNERS` file -The `OWNERS` file for each directory will typically list the creator(s) of -the component or extension it contains, along with those who are most familiar -with the directory contents. To be added to an OWNERS file create a PR and -go through the normal [code contribution process](./contributing-code.md). +The `OWNERS` file for each directory will typically list the creator(s) of the +component or extension it contains, along with those who are most familiar with +the directory contents. To be added to an OWNERS file create a PR and go through +the normal [code contribution process](./contributing-code.md). diff --git a/contributing/DESIGN_PRINCIPLES.md b/contributing/DESIGN_PRINCIPLES.md index 60200b577a30..ae0f2bd67edc 100644 --- a/contributing/DESIGN_PRINCIPLES.md +++ b/contributing/DESIGN_PRINCIPLES.md @@ -1,33 +1,49 @@ # AMP Design Principles -These design principles are meant to guide the ongoing design and development of AMP. They should help us make internally consistent decisions. +These design principles are meant to guide the ongoing design and development of +AMP. They should help us make internally consistent decisions. ## User Experience > Developer Experience > Ease of Implementation. -When in doubt, do what’s best for the end user experience, even if it means that it’s harder for the page creator to build or for the library developer to implement. +When in doubt, do what’s best for the end user experience, even if it means that +it’s harder for the page creator to build or for the library developer to +implement. ## Don’t design for a hypothetical faster future browser. -We’ve chosen to build AMP as a library in the spirit of the [extensible web manifesto](https://github.com/extensibleweb/manifesto/blob/master/README.md) to be able to fix the web of today, not the web of tomorrow. +We’ve chosen to build AMP as a library in the spirit of the +[extensible web manifesto](https://github.com/extensibleweb/manifesto/blob/master/README.md) +to be able to fix the web of today, not the web of tomorrow. -AMP should be fast in today's browsers. When certain optimizations aren't possible with today's platform, AMP developers should participate in standards development to get these added to the web platform. +AMP should be fast in today's browsers. When certain optimizations aren't +possible with today's platform, AMP developers should participate in standards +development to get these added to the web platform. ## Don’t break the web. -Ensure that if AMP has outages or problems it doesn’t hurt the rest of the web. That means if the Google AMP Cache, the URL API or the library fails it should be possible for websites and consumption apps to gracefully degrade. If something works with an AMP cache it should also work without a cache. +Ensure that if AMP has outages or problems it doesn’t hurt the rest of the web. +That means if the Google AMP Cache, the URL API or the library fails it should +be possible for websites and consumption apps to gracefully degrade. If +something works with an AMP cache it should also work without a cache. ## Solve problems on the right layer. -E.g. don’t integrate things on the client side, just because that is easier, when the user experience would be better with a server side integration. +E.g. don’t integrate things on the client side, just because that is easier, +when the user experience would be better with a server side integration. ## Only do things if they can be made fast. -Don’t introduce components or features to AMP that can’t reliably run at 60fps or hinder the instant load experience on today’s most common mobile devices. +Don’t introduce components or features to AMP that can’t reliably run at 60fps +or hinder the instant load experience on today’s most common mobile devices. ## Prioritise things that improve the user experience – but compromise when needed. -Some things can be made fast and are still a terrible user experience. AMPs should deliver a fantastic user experience and speed is just one part of that. Only compromise when lack of support for something would stop AMP from being widely used and deployed. +Some things can be made fast and are still a terrible user experience. AMPs +should deliver a fantastic user experience and speed is just one part of that. +Only compromise when lack of support for something would stop AMP from being +widely used and deployed. ## No "nicelists" or "allowed lists". -We won’t give any special treatment to specific sites, domains or origins except where needed for security or performance reasons. +We won’t give any special treatment to specific sites, domains or origins except +where needed for security or performance reasons. diff --git a/contributing/DEVELOPING.md b/contributing/DEVELOPING.md index 80dfe0a96775..ced54d1d574d 100644 --- a/contributing/DEVELOPING.md +++ b/contributing/DEVELOPING.md @@ -20,28 +20,48 @@ limitations under the License. Before you start developing in AMP, check out these resources: -- [CONTRIBUTING.md](../CONTRIBUTING.md) has details on various ways you can contribute to the AMP open source project. - - If you're developing in AMP, you should read the [Contributing code and features](./contributing-code.md) documentation, which includes information on code reviews and approvals. - - The [Ongoing participation](../CONTRIBUTING.md#ongoing-participation) section has details on various ways of getting in touch with others in the community including email and Slack. - - **If you are new to open source projects, Git/GitHub, etc.**, check out the [Tips for new open source contributors](../CONTRIBUTING.md#tips-for-new-open-source-contributors) which includes information on getting help and finding your first bug to work on. -- The [Getting Started Quick Start Guide](getting-started-quick.md) has installation steps and basic instructions for [one-time setup](getting-started-quick.md#one-time-setup), how to [build AMP & run a local server](getting-started-quick.md#build-amp--run-a-local-server) and how to [test AMP](getting-started-quick.md#test-amp). +- [CONTRIBUTING.md](../CONTRIBUTING.md) has details on various ways you can + contribute to the AMP open source project. + - If you're developing in AMP, you should read the + [Contributing code and features](./contributing-code.md) documentation, + which includes information on code reviews and approvals. + - The [Ongoing participation](../CONTRIBUTING.md#ongoing-participation) + section has details on various ways of getting in touch with others in the + community including email and Slack. + - **If you are new to open source projects, Git/GitHub, etc.**, check out the + [Tips for new open source contributors](../CONTRIBUTING.md#tips-for-new-open-source-contributors) + which includes information on getting help and finding your first bug to + work on. +- The [Getting Started Quick Start Guide](getting-started-quick.md) has + installation steps and basic instructions for + [one-time setup](getting-started-quick.md#one-time-setup), how to + [build AMP & run a local server](getting-started-quick.md#build-amp--run-a-local-server) + and how to [test AMP](getting-started-quick.md#test-amp). ## Guidelines & Style -Before you start writing code, consult these resources for guidance and guidelines on: +Before you start writing code, consult these resources for guidance and +guidelines on: - **Design**: [AMP Design Principles](DESIGN_PRINCIPLES.md) -- **JavaScript**: [Google JavaScript Code Style Guide](https://google.github.io/styleguide/jsguide.html) +- **JavaScript**: + [Google JavaScript Code Style Guide](https://google.github.io/styleguide/jsguide.html) - **CSS**: [Writing CSS For AMP Runtime](writing-css.md) - **Creating new components**: - [Instructions and Guidelines for building an AMP component](building-an-amp-extension.md) - - Learn to create your first component in this [codelab](https://codelabs.developers.google.com/codelabs/creating-your-first-amp-component/#0) - - Watch this [YouTube video](https://youtu.be/FJEhQFNKeaQ?list=PLXTOW_XMsIDTDXYO-NAi2OpEH0zyguvqX) to learn about "Building a new AMP component" -- **Integrating third-party software, embeds, services**: [Guidelines](../3p/README.md) + - Learn to create your first component in this + [codelab](https://codelabs.developers.google.com/codelabs/creating-your-first-amp-component/#0) + - Watch this + [YouTube video](https://youtu.be/FJEhQFNKeaQ?list=PLXTOW_XMsIDTDXYO-NAi2OpEH0zyguvqX) + to learn about "Building a new AMP component" +- **Integrating third-party software, embeds, services**: + [Guidelines](../3p/README.md) ## Testing -For most developers, the instructions in the [Getting Started Quick Start Guide](getting-started-quick.md) will be sufficient for building/running/testing during development. +For most developers, the instructions in the +[Getting Started Quick Start Guide](getting-started-quick.md) will be sufficient +for building/running/testing during development. For detailed information on testing, see [TESTING.md](TESTING.md). @@ -75,11 +95,17 @@ For detailed information on testing, see [TESTING.md](TESTING.md). ## Supported browsers -In general we support the 2 latest versions of major browsers like Chrome, Firefox, Edge, Safari, Opera, and UC Browser. We support desktop, phone, tablet and the web view version of these respective browsers. For iOS we support the latest 2 **major** versions which covers about 2 years. +In general we support the 2 latest versions of major browsers like Chrome, +Firefox, Edge, Safari, Opera, and UC Browser. We support desktop, phone, tablet +and the web view version of these respective browsers. For iOS we support the +latest 2 **major** versions which covers about 2 years. -Beyond that the core AMP library and builtin elements should aim for very wide browser support and we accept fixes for all browsers with market share greater than 1 percent. +Beyond that the core AMP library and builtin elements should aim for very wide +browser support and we accept fixes for all browsers with market share greater +than 1 percent. -In particular, we try to maintain "it might not be perfect but isn't broken"-support for IE 11, iOS 8, the Android 4.0 system browser and Chrome 41. +In particular, we try to maintain "it might not be perfect but isn't +broken"-support for IE 11, iOS 8, the Android 4.0 system browser and Chrome 41. ## Eng docs @@ -87,11 +113,19 @@ In particular, we try to maintain "it might not be perfect but isn't broken"-sup - [AMP Layout system](../spec/amp-html-layout.md) - [Building an AMP Extension](building-an-amp-extension.md) -We also recommend scanning the [spec](../spec/). The non-element part should help understand some of the design aspects. +We also recommend scanning the [spec](../spec/). The non-element part should +help understand some of the design aspects. ## Builds and releases -- The [AMP buildcop](buildcop.md) helps ensure that AMP's builds remain green (i.e. everything builds and all of the tests pass). If you run into issues with builds that seem unrelated to your changes see if the issue is present on [Travis](https://travis-ci.org/ampproject/amphtml/builds) and send a message to the [#contributing](https://amphtml.slack.com/messages/C9HRJ1GPN) channel on Slack ([sign up for Slack](https://bit.ly/amp-slack-signup)). -- Understanding the [AMP release process](release-schedule.md) is useful for understanding when a change in AMP will make it into production and what to do if things go wrong during the rollout of a change. +- The [AMP buildcop](buildcop.md) helps ensure that AMP's builds remain green + (i.e. everything builds and all of the tests pass). If you run into issues + with builds that seem unrelated to your changes see if the issue is present on + [Travis](https://travis-ci.org/ampproject/amphtml/builds) and send a message + to the [#contributing](https://amphtml.slack.com/messages/C9HRJ1GPN) channel + on Slack ([sign up for Slack](https://bit.ly/amp-slack-signup)). +- Understanding the [AMP release process](release-schedule.md) is useful for + understanding when a change in AMP will make it into production and what to do + if things go wrong during the rollout of a change. ## [Code of conduct](../CODE_OF_CONDUCT.md) diff --git a/contributing/ORIGIN_TRIALS.md b/contributing/ORIGIN_TRIALS.md index 6a5fea8896ed..22d2be2abd4d 100644 --- a/contributing/ORIGIN_TRIALS.md +++ b/contributing/ORIGIN_TRIALS.md @@ -1,33 +1,47 @@ # Origin Trials -Origin Trials enable developers to use an experimental feature in production and provide essential feedback. +Origin Trials enable developers to use an experimental feature in production and +provide essential feedback. -The AMP Origin Trial process is inspired by the [Chromium Origin Trial process](https://github.com/GoogleChrome/OriginTrials). +The AMP Origin Trial process is inspired by the +[Chromium Origin Trial process](https://github.com/GoogleChrome/OriginTrials). -Traditionally, a feature in experimental mode can only be used in development and cannot be pushed to production. Origin Trials allow interested developers to opt-in to a test an experimental feature in production. Origin Trial users should be mindful of the following: +Traditionally, a feature in experimental mode can only be used in development +and cannot be pushed to production. Origin Trials allow interested developers to +opt-in to a test an experimental feature in production. Origin Trial users +should be mindful of the following: - The test is for a limited time. - The feature will likely undergo some changes after an Origin Trials. -- Origin Trials present an opportunity to implement and benefit from a new feature before it’s fully live. The feature will live on the developer's site, rather than guarded by an experiment, and feedback can directly influence the direction of the feature. +- Origin Trials present an opportunity to implement and benefit from a new + feature before it’s fully live. The feature will live on the developer's site, + rather than guarded by an experiment, and feedback can directly influence the + direction of the feature. ## When to consider an Origin Trial - Not every experiment needs an Origin Trial. -- The experiment should be feature complete with a stable API at the point of the Origin Trial. -- Data from opt-in experiments is going to be insufficient and you need data from real-world users. -- The potential versioning pain is much greater than the pain of dealing with the logistics of an Origin Trial. +- The experiment should be feature complete with a stable API at the point of + the Origin Trial. +- Data from opt-in experiments is going to be insufficient and you need data + from real-world users. +- The potential versioning pain is much greater than the pain of dealing with + the logistics of an Origin Trial. - Good questions to answer with an Origin Trial: - Is this API the "right" one? ## Origin Trial - the details - No Origin Trial can last more than 3 months. -- An Origin Trial duration can be prematurely shortened by us (with 7 days of notice) if usage exceeds 0.1% of AMP page loads. -- Extending an Origin Trial requires approval from the Approvers Working Group (@ampproject/wg-approvers). +- An Origin Trial duration can be prematurely shortened by us (with 7 days of + notice) if usage exceeds 0.1% of AMP page loads. +- Extending an Origin Trial requires approval from the Approvers Working Group + (@ampproject/wg-approvers). ## Enable an Origin Trial -Include the following tag within the tag on each page that uses the Origin Trial experiment: +Include the following tag within the tag on each page that uses +the Origin Trial experiment: "amp-experiment-token" is the literal string, "amp-experiment-token". Not the token itself (which goes into the content attribute), or the name of the experiment. diff --git a/contributing/TESTING.md b/contributing/TESTING.md index daae522153a5..f791c199e829 100644 --- a/contributing/TESTING.md +++ b/contributing/TESTING.md @@ -39,7 +39,10 @@ This document provides details for testing and building your AMP code. ## Testing commands -Before running these commands, make sure you have Node.js, yarn, and Gulp installed. For installation instructions, see the [One-time setup](getting-started-quick.md#one-time-setup) section in the Quick Start guide. +Before running these commands, make sure you have Node.js, yarn, and Gulp +installed. For installation instructions, see the +[One-time setup](getting-started-quick.md#one-time-setup) section in the Quick +Start guide. | Command | Description | | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -136,19 +139,27 @@ For manual testing build AMP and start the Node.js server by running `gulp`. There are 3 serving modes: - DEFAULT mode serves unminified AMP. You want to use this during normal dev. -- COMPILED mode serves minified AMP. This is closer to the prod setup. This is only available after running `gulp dist --fortesting`. Serve MIN mode by adding `--compiled` to `gulp` command. -- CDN mode serves prod. These remote files would not reflect your local changes. Serve CDN mode by adding `--cdn` to `gulp` command. -- mode serves the bundle from the given RTV number, where is a 15 digit number. Ex. `001907161745080` - -To switch serving mode during runtime, go to http://localhost:8000/serve_mode=$mode and set the `$mode` to one of the following values: `default`, `compiled`, `cdn` or ``. +- COMPILED mode serves minified AMP. This is closer to the prod setup. This is + only available after running `gulp dist --fortesting`. Serve MIN mode by + adding `--compiled` to `gulp` command. +- CDN mode serves prod. These remote files would not reflect your local changes. + Serve CDN mode by adding `--cdn` to `gulp` command. +- mode serves the bundle from the given RTV number, where + is a 15 digit number. Ex. `001907161745080` + +To switch serving mode during runtime, go to +http://localhost:8000/serve_mode=$mode and set the `$mode` to one of the +following values: `default`, `compiled`, `cdn` or ``. ### Examples -The content in the `examples` directory can be reached at: http://localhost:8000/examples/ +The content in the `examples` directory can be reached at: +http://localhost:8000/examples/ ### Document proxy -AMP ships with a local proxy for testing production AMP documents with the local JS version. +AMP ships with a local proxy for testing production AMP documents with the local +JS version. For any public AMP document like: `http://output.jsbin.com/pegizoq/quiet`, @@ -158,16 +169,20 @@ directly: `http://localhost:8000/proxy/output.jsbin.com/pegizoq/quiet`. -**Note:** The local proxy will serve minified or unminified JS based on the current serve mode. When serve mode is `cdn`, the local proxy will serve remote JS. -When accessing minified JS make sure you run `gulp dist` with the `--fortesting` -flag so that we do not strip out the localhost code paths. (We do some -code elimination to trim down the file size for the file we deploy to production) +**Note:** The local proxy will serve minified or unminified JS based on the +current serve mode. When serve mode is `cdn`, the local proxy will serve remote +JS. When accessing minified JS make sure you run `gulp dist` with the +`--fortesting` flag so that we do not strip out the localhost code paths. (We do +some code elimination to trim down the file size for the file we deploy to +production) -If the origin resource is on HTTPS, the URLs are http://localhost:8000/proxy/s/output.jsbin.com/pegizoq/quiet +If the origin resource is on HTTPS, the URLs are +http://localhost:8000/proxy/s/output.jsbin.com/pegizoq/quiet ### A4A envelope (/a4a/, /a4a-3p/) -If you are working on AMPHTML ads, you can use the local A4A envelope for testing local and production AMP documents with the local JS version. +If you are working on AMPHTML ads, you can use the local A4A envelope for +testing local and production AMP documents with the local JS version. A4A can be run either of these two modes: @@ -177,57 +192,78 @@ A4A can be run either of these two modes: The following forms are supported: - local document: http://localhost:8000/a4a[-3p]/examples/animations.amp.html -- proxied document with local sources: http://localhost:8000/a4a[-3p]/proxy/output.jsbin.com/pegizoq/quiet +- proxied document with local sources: + http://localhost:8000/a4a[-3p]/proxy/output.jsbin.com/pegizoq/quiet When accessing minified JS make sure you run `gulp dist` with the `--fortesting` -flag so that we do not strip out the localhost code paths. (We do some -code elimination to trim down the file size for the file we deploy to production) +flag so that we do not strip out the localhost code paths. (We do some code +elimination to trim down the file size for the file we deploy to production) -If the origin resource is on HTTPS, the URLs are http://localhost:8000/a4a[-3p]/proxy/s/output.jsbin.com/pegizoq/quiet +If the origin resource is on HTTPS, the URLs are +http://localhost:8000/a4a[-3p]/proxy/s/output.jsbin.com/pegizoq/quiet -Notice that all documents are assumed to have a "fake" signature. Thus, this functionality is only available in the -`localDev` mode. +Notice that all documents are assumed to have a "fake" signature. Thus, this +functionality is only available in the `localDev` mode. Additionally, the following query parameters can be provided: - `width` - the width of the `amp-ad` (default "300") - `height` - the height of the `amp-ad` (default "250") -- `offset` - the offset to push the `amp-ad` down the page (default "0px"). Can be used to push the Ad out of the viewport, e.g. using `offset=150vh`. +- `offset` - the offset to push the `amp-ad` down the page (default "0px"). Can + be used to push the Ad out of the viewport, e.g. using `offset=150vh`. ### In-a-box envelope (/inabox/) -If you are working on AMP In-a-box Ads, you can use the local in-a-box envelope for testing local and production AMP documents with the local JS version. +If you are working on AMP In-a-box Ads, you can use the local in-a-box envelope +for testing local and production AMP documents with the local JS version. The following forms are supported: - local document: http://localhost:8000/inabox/examples/animations.amp.html -- proxied document with local sources: http://localhost:8000/inabox/proxy/output.jsbin.com/pegizoq/quiet +- proxied document with local sources: + http://localhost:8000/inabox/proxy/output.jsbin.com/pegizoq/quiet Additionally, the following query parameters can be provided: - `width` - the width of the `iframe` (default "300") - `height` - the height of the `iframe` (default "250") -- `offset` - the offset to push the `iframe` down the page (default "0px"). Can be used to push the Ad out of the viewport, e.g. using `offset=150vh`. +- `offset` - the offset to push the `iframe` down the page (default "0px"). Can + be used to push the Ad out of the viewport, e.g. using `offset=150vh`. ### Chrome extension -For testing documents on arbitrary URLs with your current local version of the AMP runtime we created a [Chrome extension](../testing/local-amp-chrome-extension/README.md). +For testing documents on arbitrary URLs with your current local version of the +AMP runtime we created a +[Chrome extension](../testing/local-amp-chrome-extension/README.md). ## Testing on Sauce Labs -We use [Sauce Labs](https://saucelabs.com) to perform cross-browser testing (thanks Sauce Labs!). In general local testing (i.e. gulp [unit|integration]) and the automatic test run on [Travis](https://travis-ci.org/ampproject/amphtml/pull_requests) that happens when you send a pull request are sufficient, but if you want to run your tests across multiple environments/browsers before sending your PR we recommend using Sauce Labs as well. +We use [Sauce Labs](https://saucelabs.com) to perform cross-browser testing +(thanks Sauce Labs!). In general local testing (i.e. gulp [unit|integration]) +and the automatic test run on +[Travis](https://travis-ci.org/ampproject/amphtml/pull_requests) that happens +when you send a pull request are sufficient, but if you want to run your tests +across multiple environments/browsers before sending your PR we recommend using +Sauce Labs as well. To run the tests on Sauce Labs: -- Create a Sauce Labs account. If you are only going to use your account for open source projects like this one you can sign up for a free [Open Sauce](https://saucelabs.com/solutions/open-source) account. (If you create an account through the normal account creation mechanism you'll be signing up for a free trial that expires; you can contact Sauce Labs customer service to switch your account to Open Sauce if you did this accidentally.) -- Set the `SAUCE_USERNAME` and `SAUCE_ACCESS_KEY` environment variables. On Linux add this to your `.bashrc`: +- Create a Sauce Labs account. If you are only going to use your account for + open source projects like this one you can sign up for a free + [Open Sauce](https://saucelabs.com/solutions/open-source) account. (If you + create an account through the normal account creation mechanism you'll be + signing up for a free trial that expires; you can contact Sauce Labs customer + service to switch your account to Open Sauce if you did this accidentally.) +- Set the `SAUCE_USERNAME` and `SAUCE_ACCESS_KEY` environment variables. On + Linux add this to your `.bashrc`: ```sh export SAUCE_USERNAME= export SAUCE_ACCESS_KEY= ``` - You can find your Sauce Labs access key on the [User Settings](https://saucelabs.com/beta/user-settings) page. + You can find your Sauce Labs access key on the + [User Settings](https://saucelabs.com/beta/user-settings) page. - Run the proxy and then run the tests: @@ -242,33 +278,64 @@ To run the tests on Sauce Labs: ./build-system/sauce_connect/stop_sauce_connect.sh ``` -- It may take several seconds for the proxy to start and for the tests to start. You can see the status of your tests on the Sauce Labs [Automated Tests](https://saucelabs.com/beta/dashboard/tests) dashboard. (You can also see the status of your proxy on the [Tunnels](https://saucelabs.com/beta/tunnels) dashboard. -- The tunnel ID used during local development is the email address of the author of the latest commit on the local branch. +- It may take several seconds for the proxy to start and for the tests to start. + You can see the status of your tests on the Sauce Labs + [Automated Tests](https://saucelabs.com/beta/dashboard/tests) dashboard. (You + can also see the status of your proxy on the + [Tunnels](https://saucelabs.com/beta/tunnels) dashboard. +- The tunnel ID used during local development is the email address of the author + of the latest commit on the local branch. ## Visual Diff Tests -In addition to building the AMP runtime and running `gulp [unit|integration]`, the automatic test run on Travis includes a set of visual diff tests to make sure a new commit to `master` does not result in unintended changes to how pages are rendered. The tests load a few well-known pages in a browser and compare the results with known good versions of the same pages. +In addition to building the AMP runtime and running `gulp [unit|integration]`, +the automatic test run on Travis includes a set of visual diff tests to make +sure a new commit to `master` does not result in unintended changes to how pages +are rendered. The tests load a few well-known pages in a browser and compare the +results with known good versions of the same pages. The technology stack used is: - [Percy](https://percy.io/), a visual regression testing service for webpages -- [Puppeteer](https://developers.google.com/web/tools/puppeteer/), a driver capable of loading webpages for diffing -- [Percy-Puppeteer](https://github.com/percy/percy-puppeteer), a framework that integrates Puppeteer with Percy -- [Headless Chrome](https://chromium.googlesource.com/chromium/src/+/lkgr/headless/README.md), the Chrome/Chromium browser in headless mode - -The [`ampproject/amphtml`](https://github.com/ampproject/amphtml) repository on GitHub is linked to the [Percy project](https://percy.io/ampproject/amphtml) of the same name. All PRs will show a check called `percy/amphtml` in addition to the `continuous-integration/travis-ci/pr` check. If your PR results in visual diff(s), clicking on the `details` link will show you the snapshots with the diffs highlighted. +- [Puppeteer](https://developers.google.com/web/tools/puppeteer/), a driver + capable of loading webpages for diffing +- [Percy-Puppeteer](https://github.com/percy/percy-puppeteer), a framework that + integrates Puppeteer with Percy +- [Headless Chrome](https://chromium.googlesource.com/chromium/src/+/lkgr/headless/README.md), + the Chrome/Chromium browser in headless mode + +The [`ampproject/amphtml`](https://github.com/ampproject/amphtml) repository on +GitHub is linked to the [Percy project](https://percy.io/ampproject/amphtml) of +the same name. All PRs will show a check called `percy/amphtml` in addition to +the `continuous-integration/travis-ci/pr` check. If your PR results in visual +diff(s), clicking on the `details` link will show you the snapshots with the +diffs highlighted. ### Failing Tests -When a test run fails due to visual diffs being present, click the `details` link next to `percy/amphtml` in your PR and examine the results. By default, Percy highlights the changes between snapshots in red. Clicking on the new snapshot will show it in its raw form. If the diffs indicate a problem that is likely to be due to your PR, you can try running the visual diffs locally in order to debug (see section below). However, if you are sure that the problem is not due to your PR, you may click the green `Approve` button on Percy to approve the snapshots and unblock your PR from being merged. +When a test run fails due to visual diffs being present, click the `details` +link next to `percy/amphtml` in your PR and examine the results. By default, +Percy highlights the changes between snapshots in red. Clicking on the new +snapshot will show it in its raw form. If the diffs indicate a problem that is +likely to be due to your PR, you can try running the visual diffs locally in +order to debug (see section below). However, if you are sure that the problem is +not due to your PR, you may click the green `Approve` button on Percy to approve +the snapshots and unblock your PR from being merged. ### Flaky Tests -If a Percy test flakes and you would like to trigger a rerun, you can't do that from within Percy. Instead, from your PR on GitHub open up the "Details" for the `continuous-integration/travis-ci/pr` check to load the Travis run for your PR. There you should see a "passed" test shard labeled "Visual Diff Tests". Click the "Restart Job" icon on just that shard to trigger a rerun on Percy. +If a Percy test flakes and you would like to trigger a rerun, you can't do that +from within Percy. Instead, from your PR on GitHub open up the "Details" for the +`continuous-integration/travis-ci/pr` check to load the Travis run for your PR. +There you should see a "passed" test shard labeled "Visual Diff Tests". Click +the "Restart Job" icon on just that shard to trigger a rerun on Percy. ### Running Visual Diff Tests Locally -You can also run the visual tests locally during development. You must first create a free Percy account at [https://percy.io](https://percy.io), create a project, and set the `PERCY_TOKEN` environment variable using the unique value you find at `https://percy.io///integrations`: +You can also run the visual tests locally during development. You must first +create a free Percy account at [https://percy.io](https://percy.io), create a +project, and set the `PERCY_TOKEN` environment variable using the unique value +you find at `https://percy.io///integrations`: ```sh export PERCY_TOKEN="" @@ -288,9 +355,12 @@ Next, run the `gulp` task that invokes the visual diff tests: gulp visual-diff --nobuild ``` -Note that if you drop the `--nobuild` flag, `gulp visual-diff` will run `gulp dist --fortesting` on each execution. +Note that if you drop the `--nobuild` flag, `gulp visual-diff` will run +`gulp dist --fortesting` on each execution. -The build will use the Percy credentials set via environment variables in the previous step, and run the tests on your local install of Chrome in headless mode. You can see the results at `https://percy.io//`. +The build will use the Percy credentials set via environment variables in the +previous step, and run the tests on your local install of Chrome in headless +mode. You can see the results at `https://percy.io//`. To see debugging info during Percy runs, you can run: @@ -304,31 +374,46 @@ To run tests without uploading snapshots to Percy, you can run: gulp visual-diff --percy_disabled ``` -The debug flags `--chrome_debug` and `--webserver_debug` can be used independently. To enable both debug flags, you can also run: +The debug flags `--chrome_debug` and `--webserver_debug` can be used +independently. To enable both debug flags, you can also run: ```sh gulp visual-diff --debug ``` -To execute only a subset of the tests (i.e., when creating or debugging an existing test) use the `--grep` regular expression flag. e.g., `gulp visual-diff --grep="amp-[a-f]"` will execute on tests that have an AMP component name between `` through ``. +To execute only a subset of the tests (i.e., when creating or debugging an +existing test) use the `--grep` regular expression flag. e.g., +`gulp visual-diff --grep="amp-[a-f]"` will execute on tests that have an AMP +component name between `` through ``. -After each run, a new set of results will be available at `https://percy.io//`. +After each run, a new set of results will be available at +`https://percy.io//`. ## Testing on devices ### Testing with ngrok -It's much faster to debug with local build (`gulp` + `http://localhost:8000/`). In Chrome you can use [DevTools port forwarding](https://developers.google.com/web/tools/chrome-devtools/remote-debugging/local-server). However, iOS Safari does not give a similar option. Instead, you can use [ngrok](https://ngrok.com/). Just [download](https://ngrok.com/download) the ngrok binary for your platform and run it like this: +It's much faster to debug with local build (`gulp` + `http://localhost:8000/`). +In Chrome you can use +[DevTools port forwarding](https://developers.google.com/web/tools/chrome-devtools/remote-debugging/local-server). +However, iOS Safari does not give a similar option. Instead, you can use +[ngrok](https://ngrok.com/). Just [download](https://ngrok.com/download) the +ngrok binary for your platform and run it like this: ```sh ngrok http 8000 ``` -Once started, the ngrok will print URLs for both `http` and `https`. E.g. `http://73774d8c.ngrok.io/` and `https://73774d8c.ngrok.io/`. These URLs can be used to debug on iOS and elsewhere. +Once started, the ngrok will print URLs for both `http` and `https`. E.g. +`http://73774d8c.ngrok.io/` and `https://73774d8c.ngrok.io/`. These URLs can be +used to debug on iOS and elsewhere. ### Testing with Firebase -For deploying and testing local AMP builds on [Firebase](https://firebase.google.com/), install firebase and initialize firebase within this directory\* (a `firebase` folder can be generated with the command, `gulp firebase`). +For deploying and testing local AMP builds on +[Firebase](https://firebase.google.com/), install firebase and initialize +firebase within this directory\* (a `firebase` folder can be generated with the +command, `gulp firebase`). ```sh npm install -g firebase-tools @@ -338,15 +423,30 @@ gulp firebase firebase deploy ``` -- When initializing firebase within the directory via `firebase init`, make sure to select the following options when asked: +- When initializing firebase within the directory via `firebase init`, make sure + to select the following options when asked: -* "Which Firebase CLI features do you want to setup for this folder?" select `Hosting: Configure and deploy Firebase Hosting sites`. +* "Which Firebase CLI features do you want to setup for this folder?" select + `Hosting: Configure and deploy Firebase Hosting sites`. * "What do you want to use as your public directory?" enter `firebase`. -* "Select a default Firebase project for this directory:" select your project name if it's already created, otherwise choose `[don't setup a new project]` and add one later. - - Note: If you haven't already, you will have to create a project via the [Firebase Console](https://console.firebase.google.com) after you are done initializing and before you deploy. Once you create the project, you can make it active in your CLI with `firebase use your-project-name` or give it an alias by selecting your project after running `firebase use --add`. -* "Configure as a single-page app (rewrite all urls to /index.html)?" select `n`. - -`gulp firebase` will generate a `firebase` folder and copy over all files from `dist`, `examples` and `test/manual`. It will rewrite all urls in the copied files to point to the local versions of AMP (i.e. the ones copied from `dist` to `firebase/dist`). When you initialize firebase, you should set the `firebase` `public` directory to `firebase`. This way `firebase deploy` will just directly copy and deploy the contents of the generated `firebase` folder. As an example, your `firebase.json` file can look something like this: +* "Select a default Firebase project for this directory:" select your project + name if it's already created, otherwise choose `[don't setup a new project]` + and add one later. + - Note: If you haven't already, you will have to create a project via the + [Firebase Console](https://console.firebase.google.com) after you are done + initializing and before you deploy. Once you create the project, you can + make it active in your CLI with `firebase use your-project-name` or give it + an alias by selecting your project after running `firebase use --add`. +* "Configure as a single-page app (rewrite all urls to /index.html)?" select + `n`. + +`gulp firebase` will generate a `firebase` folder and copy over all files from +`dist`, `examples` and `test/manual`. It will rewrite all urls in the copied +files to point to the local versions of AMP (i.e. the ones copied from `dist` to +`firebase/dist`). When you initialize firebase, you should set the `firebase` +`public` directory to `firebase`. This way `firebase deploy` will just directly +copy and deploy the contents of the generated `firebase` folder. As an example, +your `firebase.json` file can look something like this: ```json { @@ -357,15 +457,22 @@ firebase deploy } ``` -If you are only testing a single file, you can use `gulp firebase --file=path/to/my/file.amp.html` to avoid copying over all of `test/manual` and `examples`. It will copy over the specified file to `firebase/index.html`, which simplifies debugging. +If you are only testing a single file, you can use +`gulp firebase --file=path/to/my/file.amp.html` to avoid copying over all of +`test/manual` and `examples`. It will copy over the specified file to +`firebase/index.html`, which simplifies debugging. -After deploying, you can access your project publically at its hosting URL `https://your-project-name.firebaseapp.com`. +After deploying, you can access your project publically at its hosting URL +`https://your-project-name.firebaseapp.com`. -Additionally, you can create multiple projects and switch between them in the CLI using `firebase use your-project-name`. +Additionally, you can create multiple projects and switch between them in the +CLI using `firebase use your-project-name`. #### Testing Ads -Testing ads in deployed demos requires whitelisting of 3p urls. You can do this by adding your intended deployment hostname as an environemnt variable `AMP_TESTING_HOST` and using the `fortesting` flag. For example: +Testing ads in deployed demos requires whitelisting of 3p urls. You can do this +by adding your intended deployment hostname as an environemnt variable +`AMP_TESTING_HOST` and using the `fortesting` flag. For example: ```sh export AMP_TESTING_HOST="my-project.firebaseapp.com" @@ -373,11 +480,16 @@ gulp firebase --fortesting firebase deploy ``` -This will write "my-project.firebaseapp.com" as a third party url to relevant attributes in `AMP_CONFIG`, which is prepended to `amp.js` and `integration.js` files in the firebase folder. If you're curious about how this is done, feel free to inspect `build-system/tasks/firebase.js`. +This will write "my-project.firebaseapp.com" as a third party url to relevant +attributes in `AMP_CONFIG`, which is prepended to `amp.js` and `integration.js` +files in the firebase folder. If you're curious about how this is done, feel +free to inspect `build-system/tasks/firebase.js`. ## End-to-End Tests -You can run and create E2E tests locally during development. Currently tests only run on Chrome, but support for additional browsers is underway. These tests have not been added to our CI build yet - but they will be added soon. +You can run and create E2E tests locally during development. Currently tests +only run on Chrome, but support for additional browsers is underway. These tests +have not been added to our CI build yet - but they will be added soon. Run all tests with: @@ -385,6 +497,8 @@ Run all tests with: gulp e2e ``` -The task will kick off `gulp build` and then `gulp serve` before running the tests. To skip building the runtime, use `--nobuild`. +The task will kick off `gulp build` and then `gulp serve` before running the +tests. To skip building the runtime, use `--nobuild`. -[Consult the E2E testing documentation](../build-system/tasks/e2e/README.md) to learn how to create your own end-to-end tests. +[Consult the E2E testing documentation](../build-system/tasks/e2e/README.md) to +learn how to create your own end-to-end tests. diff --git a/contributing/buildcop.md b/contributing/buildcop.md index e1709f5d18b4..b1ac6942b5d2 100644 --- a/contributing/buildcop.md +++ b/contributing/buildcop.md @@ -1,33 +1,71 @@ # AMP Buildcop -The AMP buildcop is responsible for ensuring that the [master build](https://travis-ci.org/ampproject/amphtml/branches) remains green. The AMP buildcop responsibility rotates between members of the community. +The AMP buildcop is responsible for ensuring that the +[master build](https://travis-ci.org/ampproject/amphtml/branches) remains green. +The AMP buildcop responsibility rotates between members of the community. -Make sure you are a member of the [#contributing](https://amphtml.slack.com/messages/C9HRJ1GPN) channel on Slack while you are buildcop. +Make sure you are a member of the +[#contributing](https://amphtml.slack.com/messages/C9HRJ1GPN) channel on Slack +while you are buildcop. -- If the build has been red for some time, please send a note to the #contributing channel if the issue is not already reported. -- Pay attention for reports of issues with the build that the community may send to this channel. (You may want to enable notifications for this channel while you are buildcop to make this easier.) +- If the build has been red for some time, please send a note to the + #contributing channel if the issue is not already reported. +- Pay attention for reports of issues with the build that the community may send + to this channel. (You may want to enable notifications for this channel while + you are buildcop to make this easier.) ## Buildcop Tasks -1. Ensure the [master build](https://travis-ci.org/ampproject/amphtml/branches) remains green. Your goal is to keep the build from being red for more than an hour. - 1. Note that yellow builds are in the process of being created/tested so you do not need to do anything special with them. - 2. Keep an eye out for emails sent to an address starting with amp-build-cop. **You are encouraged to set up a filter so that these emails will stand out to you.** - 3. You will need to investigate whether a red build is due to a flake or due to a real issue. +1. Ensure the [master build](https://travis-ci.org/ampproject/amphtml/branches) + remains green. Your goal is to keep the build from being red for more than an + hour. + 1. Note that yellow builds are in the process of being created/tested so you + do not need to do anything special with them. + 2. Keep an eye out for emails sent to an address starting with amp-build-cop. + **You are encouraged to set up a filter so that these emails will stand + out to you.** + 3. You will need to investigate whether a red build is due to a flake or due + to a real issue. - If the issue is due to a flaky test: - - Create a ["Related to: Flaky Tests" issue](https://github.com/ampproject/amphtml/issues?q=is%3Aopen+is%3Aissue+label%3A%22Related+to%3A+Flaky+Tests%22). **Make sure to find an appropriate owner for the issue and assign it to them.** + - Create a + ["Related to: Flaky Tests" issue](https://github.com/ampproject/amphtml/issues?q=is%3Aopen+is%3Aissue+label%3A%22Related+to%3A+Flaky+Tests%22). + **Make sure to find an appropriate owner for the issue and assign it + to them.** - If needed, send a PR to disable the flaky test: - - For a normal `describe` test add [`.skip()`](https://mochajs.org/#inclusive-tests) - - For an integration test failing on a specific browser, add the corresponding `skip` function (e.g. `skipEdge()`). See the `skipXXX` functions in [\_init_tests.js](https://github.com/ampproject/amphtml/blob/master/test/_init_tests.js) for details. - - Restart the build on Travis by clicking the "Restart build" button on the build page (you must be signed into GitHub). - - If the issue is due to a real breakage, work with the appropriate owner to rollback the offending PR. Rollbacks are preferable to fixes because fixes can often cause their own breakages. -2. Keep an eye on incoming [Renovate PRs](https://github.com/ampproject/amphtml/pulls/renovate-bot), which result from an automated process to update our dependencies. + - For a normal `describe` test add + [`.skip()`](https://mochajs.org/#inclusive-tests) + - For an integration test failing on a specific browser, add the + corresponding `skip` function (e.g. `skipEdge()`). See the `skipXXX` + functions in + [\_init_tests.js](https://github.com/ampproject/amphtml/blob/master/test/_init_tests.js) + for details. + - Restart the build on Travis by clicking the "Restart build" button on + the build page (you must be signed into GitHub). + - If the issue is due to a real breakage, work with the appropriate owner + to rollback the offending PR. Rollbacks are preferable to fixes because + fixes can often cause their own breakages. +2. Keep an eye on incoming + [Renovate PRs](https://github.com/ampproject/amphtml/pulls/renovate-bot), + which result from an automated process to update our dependencies. 1. Make sure that the PR updates both package.json and yarn.lock - 2. Check the Travis logs for the PR for any new failures or unexpected results - - If there’s a failure due to a flaky test, try restarting the shard that failed - - If that doesn’t work, try syncing the branch to HEAD (tests will automatically be re-run) - - If neither of the above works, it’s possible that the package update is a breaking change. Assign the PR to someone who can look at what changed and determine how to fix it. - 3. Assuming Travis was green, make sure there are no diffs in the Percy build. - - If there are diffs that look like flakes, click “Approve” on the Percy build to unblock the PR (and ping @danielrozenberg as an FYI). + 2. Check the Travis logs for the PR for any new failures or unexpected + results + - If there’s a failure due to a flaky test, try restarting the shard that + failed + - If that doesn’t work, try syncing the branch to HEAD (tests will + automatically be re-run) + - If neither of the above works, it’s possible that the package update is + a breaking change. Assign the PR to someone who can look at what changed + and determine how to fix it. + 3. Assuming Travis was green, make sure there are no diffs in the Percy + build. + - If there are diffs that look like flakes, click “Approve” on the Percy + build to unblock the PR (and ping @danielrozenberg as an FYI). 4. Approve and merge the PR. 3. Report and triage any failing tests on _beta_ browsers: - 1. Check recent [master builds](https://travis-ci.org/ampproject/amphtml/branches) on Travis, even the green ones. Look for the `gulp [unit|integration] ... --saucelabs` task in the logs and check for any failing tests under the _beta_ test batch(es). Create issues for those tests. + 1. Check recent + [master builds](https://travis-ci.org/ampproject/amphtml/branches) on + Travis, even the green ones. Look for the + `gulp [unit|integration] ... --saucelabs` task in the logs and check for + any failing tests under the _beta_ test batch(es). Create issues for those + tests. diff --git a/contributing/building-an-amp-extension.md b/contributing/building-an-amp-extension.md index ca716ad18fc0..374ac1496a8f 100644 --- a/contributing/building-an-amp-extension.md +++ b/contributing/building-an-amp-extension.md @@ -1,11 +1,11 @@ # Building an AMP Extension -AMP can be extended to allow more functionality and components through -building open source extensions (aka custom elements). For example, AMP -provides `amp-carousel`, `amp-sidebar` and `amp-access` as -extensions. If you'd like to add an extension to support your company -video player, rich embed or just a general UI component like a star -rating viewer, you'd do this by building an extension. +AMP can be extended to allow more functionality and components through building +open source extensions (aka custom elements). For example, AMP provides +`amp-carousel`, `amp-sidebar` and `amp-access` as extensions. If you'd like to +add an extension to support your company video player, rich embed or just a +general UI component like a star rating viewer, you'd do this by building an +extension. - [Getting started](#getting-started) - [Naming](#naming) @@ -29,21 +29,28 @@ rating viewer, you'd do this by building an extension. ## Getting started -This document describes how to create a new AMP extension, which is one of the most common ways of adding a new feature to AMP. +This document describes how to create a new AMP extension, which is one of the +most common ways of adding a new feature to AMP. -Before diving into the details on creating a new AMP extension, please familiarize yourself with the [general process for contributing code and features to AMP](https://github.com/ampproject/amphtml/blob/master/contributing/contributing-code.md). Since you are adding a new extension you will likely need to follow the [process for making a significant change](https://github.com/ampproject/amphtml/blob/master/contributing/contributing-code.md#process-for-significant-changes), including filing an ["Intent to Implement" issue](https://github.com/ampproject/amphtml/labels/INTENT%20TO%20IMPLEMENT) and finding a guide before you start significant development. +Before diving into the details on creating a new AMP extension, please +familiarize yourself with the +[general process for contributing code and features to AMP](https://github.com/ampproject/amphtml/blob/master/contributing/contributing-code.md). +Since you are adding a new extension you will likely need to follow the +[process for making a significant change](https://github.com/ampproject/amphtml/blob/master/contributing/contributing-code.md#process-for-significant-changes), +including filing an +["Intent to Implement" issue](https://github.com/ampproject/amphtml/labels/INTENT%20TO%20IMPLEMENT) +and finding a guide before you start significant development. ## Naming -All AMP extensions (and built-in elements) have their tag names prefixed -with `amp-`. Make sure to choose an accurate and clear name for your -extension. For example, video players are also suffixed with `-player` -(e.g. amp-brid-player). +All AMP extensions (and built-in elements) have their tag names prefixed with +`amp-`. Make sure to choose an accurate and clear name for your extension. For +example, video players are also suffixed with `-player` (e.g. amp-brid-player). ## Directory structure -You create your extension's files inside the `extensions/` directory. -The directory structure is below: +You create your extension's files inside the `extensions/` directory. The +directory structure is below: ```sh /extensions/amp-my-element/ @@ -60,21 +67,22 @@ The directory structure is below: └── OWNERS # Owners file. Primary contact(s) for the extension. (req'd) ``` -In most cases you'll only create the required (req'd) files. If your element does not need custom CSS, you don't need to create the CSS file. +In most cases you'll only create the required (req'd) files. If your element +does not need custom CSS, you don't need to create the CSS file. ## Extend AMP.BaseElement -Almost all AMP extensions extend AMP.BaseElement, which provides some -hookups and callbacks for you to override in order to implement and -customize your element behavior. These callbacks are explained below in -the BaseElement Callbacks section, and are also explained inline in the +Almost all AMP extensions extend AMP.BaseElement, which provides some hookups +and callbacks for you to override in order to implement and customize your +element behavior. These callbacks are explained below in the BaseElement +Callbacks section, and are also explained inline in the [BaseElement](https://github.com/ampproject/amphtml/blob/master/src/base-element.js#L26) class. ### Element class -The following shows the overall structure of your element implementation -file (extensions/amp-my-element/0.1/amp-my-element.js). +The following shows the overall structure of your element implementation file +(extensions/amp-my-element/0.1/amp-my-element.js). ```js import {func1, func2} from '../src/module'; @@ -123,10 +131,10 @@ AMP.extension('amp-my-element', '0.1', AMP => { - **Default**: Does nothing - **Override**: Rarely. -- **[Vsync](https://github.com/ampproject/amphtml/blob/master/src/service/vsync-impl.js) Context**: None -- **Usage**: If your extension provides different implementations - depending on a late runtime condition (e.g. type attribute on the - element, platform) +- **[Vsync](https://github.com/ampproject/amphtml/blob/master/src/service/vsync-impl.js) + Context**: None +- **Usage**: If your extension provides different implementations depending on a + late runtime condition (e.g. type attribute on the element, platform) - **Example Usage**: amp-ad, amp-app-banner #### buildCallback @@ -134,29 +142,28 @@ AMP.extension('amp-my-element', '0.1', AMP => { - **Default**: Does nothing - **Override**: Almost always - **Vsync Context**: Mutate -- **Usage**: If your element has UI elements this is where you should - create your DOM structure and append it to the element. You can also - read the attributes (e.g. width, height…) the user provided on your - element in this callback. -- **Warning**: Don't load remote resources during the buildCallback. This - not only circumvents the AMP resources manager, but it will also lead to - higher data charges for users because all these resources will be loaded - before layouting needs to happen. -- **Warning 2**: Do the least needed work here, and don't build DOM that - is not needed at this point. +- **Usage**: If your element has UI elements this is where you should create + your DOM structure and append it to the element. You can also read the + attributes (e.g. width, height…) the user provided on your element in this + callback. +- **Warning**: Don't load remote resources during the buildCallback. This not + only circumvents the AMP resources manager, but it will also lead to higher + data charges for users because all these resources will be loaded before + layouting needs to happen. +- **Warning 2**: Do the least needed work here, and don't build DOM that is not + needed at this point. #### preconnectCallback - **Default**: Does nothing. - **Vsync Context**: None (Neither mutate nor measure) -- **Override**: Sometimes, if your element will be loading remote - resources. +- **Override**: Sometimes, if your element will be loading remote resources. - **Usage**: Use to instruct AMP which hosts to preconnect to, and which - resources to preload/prefetch; this allows AMP to delegate to the browser - to get a performance boost by preconnecting, preloading and prefetching - resources via preconnect service. -- **Example Usage**: [Instagram uses this to - preconnect](https://github.com/ampproject/amphtml/blob/master/extensions/amp-instagram/0.1/amp-instagram.js) + resources to preload/prefetch; this allows AMP to delegate to the browser to + get a performance boost by preconnecting, preloading and prefetching resources + via preconnect service. +- **Example Usage**: + [Instagram uses this to preconnect](https://github.com/ampproject/amphtml/blob/master/extensions/amp-instagram/0.1/amp-instagram.js) to instagram hosts. #### createPlaceholderCallback @@ -164,19 +171,17 @@ AMP.extension('amp-my-element', '0.1', AMP => { - **Default**: Does nothing. - **Vsync Context**: Mutate - **Override**: Sometimes. If your component provides a way to dynamically - create a lightweight placeholder. This gets called only if the element - doesn't already have a publisher-provided placeholder (through [the - placeholder - attribute](https://github.com/ampproject/amphtml/blob/master/spec/amp-html-layout.md#placeholder)). -- **Usage**: Create placeholder DOM and return it. For example, - amp-instagram uses this to create a placeholder dynamically by creating - an amp-img placeholder instead of loading the iframe, leaving the iframe - loading to layoutCallback. -- **Warning**: Only use amp-elements for creating placeholders that - require external resource loading. This allows runtime to create this - early but still defer the resource loading and management to AMP - resources manager. Don't create or load heavyweight resources (e.g. - iframe…). + create a lightweight placeholder. This gets called only if the element doesn't + already have a publisher-provided placeholder (through + [the placeholder attribute](https://github.com/ampproject/amphtml/blob/master/spec/amp-html-layout.md#placeholder)). +- **Usage**: Create placeholder DOM and return it. For example, amp-instagram + uses this to create a placeholder dynamically by creating an amp-img + placeholder instead of loading the iframe, leaving the iframe loading to + layoutCallback. +- **Warning**: Only use amp-elements for creating placeholders that require + external resource loading. This allows runtime to create this early but still + defer the resource loading and management to AMP resources manager. Don't + create or load heavyweight resources (e.g. iframe…). - **Example Usage**: amp-instagram. #### onLayoutMeasure @@ -192,24 +197,24 @@ AMP.extension('amp-my-element', '0.1', AMP => { - **Default**: Does nothing. - **Vsync Context**: Mutate - **Override**: Almost always. -- **Usage**: Use this to actually render the final version of your - element. If the element should load a video, this is where you load the - video. This needs to return a promise that resolves when the element is - considered "laid out" - usually this means load event has fired but can - be different from element to element. Note that load events usually are - fired very early so if there's another event that your element can - listen to that have a better meaning of ready-ness, use that to resolve - your promise instead - for example: [amp-youtube](https://github.com/ampproject/amphtml/blob/master/extensions/amp-youtube/0.1/amp-youtube.js) uses the - playerready event that the underlying YT Player - iframe sends to resolve the layoutCallback promise. +- **Usage**: Use this to actually render the final version of your element. If + the element should load a video, this is where you load the video. This needs + to return a promise that resolves when the element is considered "laid out" - + usually this means load event has fired but can be different from element to + element. Note that load events usually are fired very early so if there's + another event that your element can listen to that have a better meaning of + ready-ness, use that to resolve your promise instead - for example: + [amp-youtube](https://github.com/ampproject/amphtml/blob/master/extensions/amp-youtube/0.1/amp-youtube.js) + uses the playerready event that the underlying YT Player iframe sends to + resolve the layoutCallback promise. #### firstLayoutCompleted - **Default**: Hide element's placeholder. - **Vsync Context**: Mutate -- **Override**: Sometimes. If you'd like to override default behavior and - not hide the placeholder when the element is considered first laid out. - Sometimes you wanna control when to hide the placeholder. +- **Override**: Sometimes. If you'd like to override default behavior and not + hide the placeholder when the element is considered first laid out. Sometimes + you wanna control when to hide the placeholder. - **Example Usage**: amp-anim #### pauseCallback @@ -217,9 +222,8 @@ AMP.extension('amp-my-element', '0.1', AMP => { - **Default**: Does nothing. - **Vsync Context**: Mutate - **Called**: When you swipe away from a document in a viewer. Called on - children of lightbox when you close a lightbox instance, called on - carousel children when the slide is not the active slide. And possibly - other places. + children of lightbox when you close a lightbox instance, called on carousel + children when the slide is not the active slide. And possibly other places. - **Override**: Sometimes. Most likely if you're building a player. - **Usage**: Use to pause video, slideshow auto-advance...etc - **Example Usage**: amp-video, amp-youtube @@ -230,16 +234,15 @@ AMP.extension('amp-my-element', '0.1', AMP => { - **Vsync Context**: Mutate - **Override**: Sometimes. - **Usage**: Use to restart the slideshow auto-advance. -- **Note**: This is not used widely yet because it's not possible to - resume video playback for example on mobile. +- **Note**: This is not used widely yet because it's not possible to resume + video playback for example on mobile. #### unlayoutOnPause - **Default**: Returns false. - **Vsync Context**: Mutate -- **Override**: If your element doesn't provide a pausing mechanism, - instead override this to unlayout the element when AMP tries to pause - it. +- **Override**: If your element doesn't provide a pausing mechanism, instead + override this to unlayout the element when AMP tries to pause it. - **Return**: True if you want unlayoutCallback to be called when paused. - **Usage Example**: amp-brightcove @@ -248,8 +251,8 @@ AMP.extension('amp-my-element', '0.1', AMP => { - **Default**: Does nothing. - **Vsync Context**: Mutate - **Override**: Sometimes. -- **Usage**: Use to remove and unload heavyweight resources like iframes, - video, audio and others that your element has created. +- **Usage**: Use to remove and unload heavyweight resources like iframes, video, + audio and others that your element has created. - **Return**: **True** if your element need to re-layout. - **Usage Example**: amp-iframe @@ -257,24 +260,24 @@ AMP.extension('amp-my-element', '0.1', AMP => { - **Default**: Does nothing. - **Override**: Rarely. -- **Usage**: Use if your element need to know when it comes into viewport - and when it goes out of it for finer control. +- **Usage**: Use if your element need to know when it comes into viewport and + when it goes out of it for finer control. - **Usage Example**: amp-carousel, amp-anim ## Element styling -You can write a stylesheet to style your element to provide a minimal -visual appeal. Your element structure should account for whether you -want users (publishers and developers using your element) to customize -the default styling you're providing and allow for easy CSS classes -and/or well-structure DOM elements. +You can write a stylesheet to style your element to provide a minimal visual +appeal. Your element structure should account for whether you want users +(publishers and developers using your element) to customize the default styling +you're providing and allow for easy CSS classes and/or well-structure DOM +elements. -Element styles are loaded when the element script itself is included in -an AMP doc. You tell AMP which CSS belongs to this element when -registering the element (see below). +Element styles are loaded when the element script itself is included in an AMP +doc. You tell AMP which CSS belongs to this element when registering the element +(see below). -Class names prefixed with `i-amphtml` are considered private. Publishers -are not allowed to use them for customization (enforced by AMP validator). +Class names prefixed with `i-amphtml` are considered private. Publishers are not +allowed to use them for customization (enforced by AMP validator). Class names prefixed with `amp-` are public css classes that can be customized by publishers. All such classes should be documented in the component-specific @@ -283,9 +286,9 @@ either `i-amphtml-` or `amp-`. ## Register element with AMP -Once you have implemented your AMP element, you need to register it with -AMP; all AMP extensions are prefixed with `amp-`. This is where you -tell AMP which class to use for this tag name and which CSS to load. +Once you have implemented your AMP element, you need to register it with AMP; +all AMP extensions are prefixed with `amp-`. This is where you tell AMP which +class to use for this tag name and which CSS to load. ```javascript AMP.extension('amp-carousel', '0.1', AMP => { @@ -295,18 +298,17 @@ AMP.extension('amp-carousel', '0.1', AMP => { ## Actions and events -AMP provides a framework for [elements to fire their own -events](https://github.com/ampproject/amphtml/blob/master/spec/amp-actions-and-events.md) -to allow users of that element to listen and react to the events. For -example, amp-form extension fires a few events on <form> elements -like `submit-success`. This allow publishers to listen to that event -and react to it, for example, by launching a lightbox to display a -message. +AMP provides a framework for +[elements to fire their own events](https://github.com/ampproject/amphtml/blob/master/spec/amp-actions-and-events.md) +to allow users of that element to listen and react to the events. For example, +amp-form extension fires a few events on <form> elements like +`submit-success`. This allow publishers to listen to that event and react to it, +for example, by launching a lightbox to display a message. -The other part of the event-system in AMP is actions. When listening to -an event on an element usually you'd like to trigger an action (possibly -on other elements). For example, in the example above, the publisher is -executing the `open` action on `lightbox`. +The other part of the event-system in AMP is actions. When listening to an event +on an element usually you'd like to trigger an action (possibly on other +elements). For example, in the example above, the publisher is executing the +`open` action on `lightbox`. The syntax for using this on elements is as follow: @@ -316,8 +318,8 @@ The syntax for using this on elements is as follow: > ``` -To fire events on your element use AMP's action service and the -`.trigger` method. +To fire events on your element use AMP's action service and the `.trigger` +method. ```javascript actionServiceForDoc(doc.documentElement).trigger( @@ -327,17 +329,16 @@ actionServiceForDoc(doc.documentElement).trigger( ); ``` -And to expose actions use `registerAction` method that your element -inherits from `BaseElement`. +And to expose actions use `registerAction` method that your element inherits +from `BaseElement`. ```javascript this.registerAction('close', this.close.bind(this)); ``` -Your element could also choose to override the `activate` method -inherited from BaseElement that would define the default action for your -element. For example amp-lightbox overrides activate to define the open -default case. +Your element could also choose to override the `activate` method inherited from +BaseElement that would define the default action for your element. For example +amp-lightbox overrides activate to define the open default case. Make sure your element documentation documents the events and actions it exposes. @@ -345,18 +346,16 @@ exposes. ## Sub-elements ownership AMP elements are usually discovered and scheduled by the AMP runtime -automatically and managed through Resources. In some cases an AMP -element might want to control and own when its sub-elements get -scheduled and not leave that to the AMP runtime. An example to this is -the <amp-carousel> component, where it wants to schedule -preloading/pre-rendering or layouting of its cells based on the window -the user is in. - -AMP provides a way for an element to control this by setting the owner -on the element you want to control. In the carousel example, the component loops -over all its elements and sets itself as the owner of these elements. -The AMP runtime will not manage scheduling layouting for elements that have -owners. +automatically and managed through Resources. In some cases an AMP element might +want to control and own when its sub-elements get scheduled and not leave that +to the AMP runtime. An example to this is the <amp-carousel> component, +where it wants to schedule preloading/pre-rendering or layouting of its cells +based on the window the user is in. + +AMP provides a way for an element to control this by setting the owner on the +element you want to control. In the carousel example, the component loops over +all its elements and sets itself as the owner of these elements. The AMP runtime +will not manage scheduling layouting for elements that have owners. ```javascript this.cells_ = this.getRealChildren(); @@ -368,12 +367,11 @@ this.cells_.forEach(cell => { }); ``` -An element can then later call `schedulePreload` or `scheduleLayout` to -schedule preload or layout respectively. For example, <amp-carousel -type=slider> (Slider instance of amp-carousel) calls -`schedulePreload` for the next/previous slide when the user moves -forward/backward in the slides and then calls `scheduleLayout` for the -current slide when the user moves to it. +An element can then later call `schedulePreload` or `scheduleLayout` to schedule +preload or layout respectively. For example, <amp-carousel type=slider> +(Slider instance of amp-carousel) calls `schedulePreload` for the next/previous +slide when the user moves forward/backward in the slides and then calls +`scheduleLayout` for the current slide when the user moves to it. ```javascript const owners = Services.ownersForDoc(this.element); @@ -385,19 +383,18 @@ owners.schedulePause(this.element, oldSlide); owners.schedulePreload(this.element, nextSlide); ``` -It's important to understand that the parent/owner element is -responsible for managing all of its children (except for placeholders, -see below). This means you need to make sure your element updates -whether the child is in viewport and when to schedule different phases -for the element. +It's important to understand that the parent/owner element is responsible for +managing all of its children (except for placeholders, see below). This means +you need to make sure your element updates whether the child is in viewport and +when to schedule different phases for the element. ### Nested sub-elements -Your element should anticipate its sub-elements to nest some more -amp-elements and schedule preload or layout for these as well, otherwise -the element will never be preloaded or laid out. This is true to all -nested amp-elements that are not placeholders. AMP runtime will schedule -nested amp-elements that are placeholders. +Your element should anticipate its sub-elements to nest some more amp-elements +and schedule preload or layout for these as well, otherwise the element will +never be preloaded or laid out. This is true to all nested amp-elements that are +not placeholders. AMP runtime will schedule nested amp-elements that are +placeholders. ```html @@ -413,56 +410,56 @@ nested amp-elements that are placeholders. ## Allowing proper validations -One of AMP's features is that a document can be checked against -validation rules to confirm it's AMP-valid. When you implement your -element, AMP validator needs to be updated to add rules for your element -to keep documents using your element valid. In order to do that you need -to file an issue on the GitHub repo select "Related to: Validator" and -mention what rules the validator needs to validate. This usually -includes +One of AMP's features is that a document can be checked against validation rules +to confirm it's AMP-valid. When you implement your element, AMP validator needs +to be updated to add rules for your element to keep documents using your element +valid. In order to do that you need to file an issue on the GitHub repo select +"Related to: Validator" and mention what rules the validator needs to validate. +This usually includes - Your element tag-name - Required attributes for the element - Specific values that an attribute accept (e.g. `myattr="TYPE1|TYPE2"`) -- Layouts your element supports (see [Layout specs](https://github.com/ampproject/amphtml/blob/master/spec/amp-html-layout.md) and [Layouts supported in your element](#layouts-supported-in-your-element)) -- If there are restrictions where your element can or can't appear (e.g. disallowed_ancestory, mandatory_parent...) +- Layouts your element supports (see + [Layout specs](https://github.com/ampproject/amphtml/blob/master/spec/amp-html-layout.md) + and [Layouts supported in your element](#layouts-supported-in-your-element)) +- If there are restrictions where your element can or can't appear (e.g. + disallowed_ancestory, mandatory_parent...) -For more details take a look at [Contributing Component Validator -Rules](https://github.com/ampproject/amphtml/blob/master/contributing/component-validator-rules.md). +For more details take a look at +[Contributing Component Validator Rules](https://github.com/ampproject/amphtml/blob/master/contributing/component-validator-rules.md). ## Performance considerations ### Pre-rendering and placeholders -Another enabling feature of instant-web in AMP is support for -prerendering in a way that does not consume loads of data and does not -waste too much of the user's device resources. AMP does this by strictly -controlling resource loading and rendering. +Another enabling feature of instant-web in AMP is support for prerendering in a +way that does not consume loads of data and does not waste too much of the +user's device resources. AMP does this by strictly controlling resource loading +and rendering. -If your extension is lightweight, it might be worth enabling -pre-rendering of your elements so that users will be able to see it -appear instantly when they click on an article. +If your extension is lightweight, it might be worth enabling pre-rendering of +your elements so that users will be able to see it appear instantly when they +click on an article. Sometimes fully pre-rendering the element isn't an option because it is -heavyweight. Your element might want to opt into creating a dynamic -placeholder for itself (in case a placeholder wasn't provided by the -developer/publisher who is using your element). This allows elements to -display content as fast as possible and allow prerendering that -placeholder. Learn [more about placeholder -elements](https://github.com/ampproject/amphtml/blob/master/spec/amp-html-layout.md#placeholder). +heavyweight. Your element might want to opt into creating a dynamic placeholder +for itself (in case a placeholder wasn't provided by the developer/publisher who +is using your element). This allows elements to display content as fast as +possible and allow prerendering that placeholder. Learn +[more about placeholder elements](https://github.com/ampproject/amphtml/blob/master/spec/amp-html-layout.md#placeholder). -NOTE: Make sure not to request external resources in the pre-render -phase. Requests to the publisher's origin itself are OK. If in doubt, -please flag this in review. +NOTE: Make sure not to request external resources in the pre-render phase. +Requests to the publisher's origin itself are OK. If in doubt, please flag this +in review. AMP will automatically call your element's -[createPlaceholderCallback](#createplaceholdercallback) during -build step if it didn't detect a placeholder was provided. This allows -you to create your own placeholder. Here's an example of how -`amp-instagram` element used this callback to create a dynamic -placeholder of an `amp-img` element to avoid loading the heavyweight -instagram iframe embed during pre-rendering and instead loads just the -image directly from instagram media endpoint. +[createPlaceholderCallback](#createplaceholdercallback) during build step if it +didn't detect a placeholder was provided. This allows you to create your own +placeholder. Here's an example of how `amp-instagram` element used this callback +to create a dynamic placeholder of an `amp-img` element to avoid loading the +heavyweight instagram iframe embed during pre-rendering and instead loads just +the image directly from instagram media endpoint. ```javascript class AmpInstagram extends AMP.BaseElement { @@ -506,20 +503,20 @@ class AmpInstagram extends AMP.BaseElement { } ``` -**Important**: One thing to keep in mind is that when you create a -placeholder, use the amp- provided elements when loading external -resources. This is most likely going to be `amp-img` like in the -instagram case above. This still allows AMP resource manager to control -when these resources get loaded and rendered as oppose to using the -HTML-native `img` tag which will be out of AMP resource management. +**Important**: One thing to keep in mind is that when you create a placeholder, +use the amp- provided elements when loading external resources. This is most +likely going to be `amp-img` like in the instagram case above. This still allows +AMP resource manager to control when these resources get loaded and rendered as +oppose to using the HTML-native `img` tag which will be out of AMP resource +management. #### Loading indicators -Consider showing a loading indicator if your element is expected to take -a long time to load (for example, loading a GIF, video or iframe). AMP -has a built-in mechanism to show a loading indicator simply by -whitelisting your element to show it. You can do that inside layout.js -file in the `LOADING_ELEMENTS_` object. +Consider showing a loading indicator if your element is expected to take a long +time to load (for example, loading a GIF, video or iframe). AMP has a built-in +mechanism to show a loading indicator simply by whitelisting your element to +show it. You can do that inside layout.js file in the `LOADING_ELEMENTS_` +object. ```javascript export const LOADING_ELEMENTS_ = { @@ -531,24 +528,23 @@ export const LOADING_ELEMENTS_ = { ### Destroying heavyweight resources -To stay good to our promise of lowering resources usage especially on -mobile, elements that create and load heavyweight resources (e.g. -iframes, video, very large images, an expensive timer or computation...) -need to be destroyed when they are no longer needed. +To stay good to our promise of lowering resources usage especially on mobile, +elements that create and load heavyweight resources (e.g. iframes, video, very +large images, an expensive timer or computation...) need to be destroyed when +they are no longer needed. AMP signals to your element that it needs to do that with -[unlayoutCallback](#unlayoutcallback). AMP calls this when the -document becomes inactive; like when the user swipes away from the -document to another one or when they switch tabs. +[unlayoutCallback](#unlayoutcallback). AMP calls this when the document becomes +inactive; like when the user swipes away from the document to another one or +when they switch tabs. -This might be also be called in special cases like if your element is -used as an amp-carousel cell and it was swiped away to become outside -the viewport. This will only happen if your element sets -`unlayoutOnPause`. Carousel by default only pauses the elements that -are outside its viewport. +This might be also be called in special cases like if your element is used as an +amp-carousel cell and it was swiped away to become outside the viewport. This +will only happen if your element sets `unlayoutOnPause`. Carousel by default +only pauses the elements that are outside its viewport. -Here's an example of how `amp-instagram` destroys the iframe it has -embedded when `unlayoutCallback` is called. +Here's an example of how `amp-instagram` destroys the iframe it has embedded +when `unlayoutCallback` is called. ```javascript /** @override */ @@ -565,54 +561,52 @@ unlayoutCallback() { } ``` -Note if your element unlayoutCallback destroys the resources, it -probably wants to return true in order to signal to AMP the need to call -`layoutCallback` again once the document is active. Otherwise your -element will never be re-laid out. +Note if your element unlayoutCallback destroys the resources, it probably wants +to return true in order to signal to AMP the need to call `layoutCallback` again +once the document is active. Otherwise your element will never be re-laid out. ### vsync, mutateElement, and changeSize -AMP provides multiple utilities to optimize many mutations and measuring -for better performance. These include vsync service with a mutate and -measure utility method that will synchronize all measuring happening in -short period of time together and then do all the mutating in a -requestAnimationFrame or similar cycles. +AMP provides multiple utilities to optimize many mutations and measuring for +better performance. These include vsync service with a mutate and measure +utility method that will synchronize all measuring happening in short period of +time together and then do all the mutating in a requestAnimationFrame or similar +cycles. ### Loading external resources -If your extension needs to load external resources (like an sdk) then -you might need to add proper third party integration for it to work and -use the proper third party iframe. Loading external resources is only -allowed inside a 3p iframe which AMP serves on a different domain for -security and performance reasons. Take a look at adding +If your extension needs to load external resources (like an sdk) then you might +need to add proper third party integration for it to work and use the proper +third party iframe. Loading external resources is only allowed inside a 3p +iframe which AMP serves on a different domain for security and performance +reasons. Take a look at adding [<amp-facebook>](https://github.com/ampproject/amphtml/pull/1479/files) extension PR for examples of 3p integration. -Read about [Inclusion of third party software, embeds and services into -AMP](https://github.com/ampproject/amphtml/blob/master/3p/README.md). +Read about +[Inclusion of third party software, embeds and services into AMP](https://github.com/ampproject/amphtml/blob/master/3p/README.md). -For contrast, take a look at amp-instagram which does NOT require an SDK -to be loaded in order to embed a post, instead it provides an -iframe-based embedding allowing amp-instagram extension to use a normal -iframe with no 3p integration needed, similarly, amp-youtube and others. +For contrast, take a look at amp-instagram which does NOT require an SDK to be +loaded in order to embed a post, instead it provides an iframe-based embedding +allowing amp-instagram extension to use a normal iframe with no 3p integration +needed, similarly, amp-youtube and others. ## Layouts supported in your element -AMP defines different layouts that elements can choose whether or not to -support Your element needs to announce which layouts it supports through -overriding the `isLayoutSupported(layout)` callback and returning true -if the element supports that layout. [Read more about AMP Layout -System](https://github.com/ampproject/amphtml/blob/master/spec/amp-html-layout.md) -and [Layout -Types](https://github.com/ampproject/amphtml/blob/master/spec/amp-html-layout.md#layout). +AMP defines different layouts that elements can choose whether or not to support +Your element needs to announce which layouts it supports through overriding the +`isLayoutSupported(layout)` callback and returning true if the element supports +that layout. +[Read more about AMP Layout System](https://github.com/ampproject/amphtml/blob/master/spec/amp-html-layout.md) +and +[Layout Types](https://github.com/ampproject/amphtml/blob/master/spec/amp-html-layout.md#layout). ### What layout should your element support? -After understanding each layout type, if it makes sense, support all of -them. Otherwise choose what makes sense to your element. A popular -support choice is to support size-defined layouts (Fixed, Fixed Height, -Responsive and Fill) through using the utility `isLayoutSizeDefined` -in `layout.js`. +After understanding each layout type, if it makes sense, support all of them. +Otherwise choose what makes sense to your element. A popular support choice is +to support size-defined layouts (Fixed, Fixed Height, Responsive and Fill) +through using the utility `isLayoutSizeDefined` in `layout.js`. For example, `amp-pixel` only supports fixed layout. @@ -640,16 +634,14 @@ class AmpSlides extends AMP.BaseElement { Most newly created elements are initially launched as [experiments](https://github.com/ampproject/amphtml/blob/master/tools/experiments/README.md). -This allows people to experiment with using the new element and provide -the author(s) with feedback. It also provides the AMP Team with the -opportunity to monitor for any potential errors. This is especially -required if the validator hasn't been updated yet to allow your newly -created extension, otherwise people using it in production will -invalidate all their AMP documents. +This allows people to experiment with using the new element and provide the +author(s) with feedback. It also provides the AMP Team with the opportunity to +monitor for any potential errors. This is especially required if the validator +hasn't been updated yet to allow your newly created extension, otherwise people +using it in production will invalidate all their AMP documents. -Add your extension as an experiment in the -`amphtml/tools/experiments` file by adding a record for your extension -in EXPERIMENTS variable. +Add your extension as an experiment in the `amphtml/tools/experiments` file by +adding a record for your extension in EXPERIMENTS variable. ```javascript /** @const {!Array} */ @@ -667,7 +659,9 @@ const EXPERIMENTS = [ ]; ``` -And then protecting your code with a check `isExperimentOn(win, 'amp-my-element')` and only execute your code when it is on. +And then protecting your code with a check +`isExperimentOn(win, 'amp-my-element')` and only execute your code when it is +on. ```javascript import {isExperimentOn} from '../../../src/experiments'; @@ -717,16 +711,21 @@ AMP.extension('amp-my-element', '0.1', AMP => { ### Enabling and removing your experiment Users wanting to experiment with your element can then go to the -[experiments page](https://cdn.ampproject.org/experiments.html) and -enable your experiment. +[experiments page](https://cdn.ampproject.org/experiments.html) and enable your +experiment. -If you are testing on your localhost, use the command `AMP.toggleExperiment(id, true/false)` to enable the experiment. +If you are testing on your localhost, use the command +`AMP.toggleExperiment(id, true/false)` to enable the experiment. -File a github issue to cleanup your experiment. Assign it to yourself as a reminder to remove your experiment and code checks. Removal of your experiment happens after the extension has been thoroughly tested and all issues have been addressed. +File a github issue to cleanup your experiment. Assign it to yourself as a +reminder to remove your experiment and code checks. Removal of your experiment +happens after the extension has been thoroughly tested and all issues have been +addressed. ## Documenting your element -Create a .md file that serves as the main documentation for your element. This document should include: +Create a .md file that serves as the main documentation for your element. This +document should include: - Summary table - Overview @@ -735,27 +734,30 @@ Create a .md file that serves as the main documentation for your element. This d - Attributes to specify (optional and required) - Validation -For samples of element documentation, see: [amp-list](https://github.com/ampproject/amphtml/blob/master/extensions/amp-list/amp-list.md), [amp-instagram](https://github.com/ampproject/amphtml/blob/master/extensions/amp-instagram/amp-instagram.md), [amp-carousel](https://github.com/ampproject/amphtml/blob/master/extensions/amp-carousel/amp-carousel.md) +For samples of element documentation, see: +[amp-list](https://github.com/ampproject/amphtml/blob/master/extensions/amp-list/amp-list.md), +[amp-instagram](https://github.com/ampproject/amphtml/blob/master/extensions/amp-instagram/amp-instagram.md), +[amp-carousel](https://github.com/ampproject/amphtml/blob/master/extensions/amp-carousel/amp-carousel.md) ## Example of using your extension -This greatly helps users to understand and demonstrate how -your element works, and provides an easy start-point for them to -experiment with it. This is basically where you actually build an AMP -HTML document and use your element in it by creating a file in the -`examples/` directory, usually with the `my-element.amp.html` file -name. Browse that directory to see examples for other elements and -extensions. +This greatly helps users to understand and demonstrate how your element works, +and provides an easy start-point for them to experiment with it. This is +basically where you actually build an AMP HTML document and use your element in +it by creating a file in the `examples/` directory, usually with the +`my-element.amp.html` file name. Browse that directory to see examples for other +elements and extensions. -Also consider contributing to -[ampbyexample.com](https://ampbyexample.com/) on +Also consider contributing to [ampbyexample.com](https://ampbyexample.com/) on [GitHub](https://github.com/ampproject/amp-by-example). ## Updating build configs -In order for your element to build correctly you would need to make few -changes to [`build-system/compile/bundles.config.js`](../build-system/compile/bundles.config.js) to tell it about your -extension, its files and its examples. You will need to add an entry in the `extensionBundles` array. +In order for your element to build correctly you would need to make few changes +to +[`build-system/compile/bundles.config.js`](../build-system/compile/bundles.config.js) +to tell it about your extension, its files and its examples. You will need to +add an entry in the `extensionBundles` array. ```javascript exports.extensionBundles = [ @@ -768,30 +770,29 @@ exports.extensionBundles = [ ## Versioning -AMP runtime is currently in v0 major version. Extensions versions are -maintained separately. If your changes to your non-experimental -extension makes breaking changes that are not backward compatible you -should version your extension. This would usually be by creating a 0.2 -directory next to your 0.1. +AMP runtime is currently in v0 major version. Extensions versions are maintained +separately. If your changes to your non-experimental extension makes breaking +changes that are not backward compatible you should version your extension. This +would usually be by creating a 0.2 directory next to your 0.1. -When version 0.2 is under development, make sure that `latestVersion` is -set to 0.1 for both the 0.1 and 0.2 entries in `extensionBundles`. Once 0.2 -is ready to be released, `latestVersion` can be changed to 0.2. +When version 0.2 is under development, make sure that `latestVersion` is set to +0.1 for both the 0.1 and 0.2 entries in `extensionBundles`. Once 0.2 is ready to +be released, `latestVersion` can be changed to 0.2. -If your extension is still in experiments breaking changes usually are -fine so you can just update the same version. +If your extension is still in experiments breaking changes usually are fine so +you can just update the same version. ## Unit tests -Make sure you write good coverage for your code. We require unit tests -for all checked in code. We use the following frameworks for testing: +Make sure you write good coverage for your code. We require unit tests for all +checked in code. We use the following frameworks for testing: - [Mocha](https://mochajs.org/), our test framework - [Karma](https://karma-runner.github.io/), our tests runner - [Sinon](http://sinonjs.org/), spies, stubs and mocks. -For faster testing during development, consider using --files argument -to only run your extensions' tests. +For faster testing during development, consider using --files argument to only +run your extensions' tests. ```shell $ gulp unit --files=extensions/amp-my-element/0.1/test/test-amp-my-element.js --watch @@ -800,11 +801,10 @@ $ gulp unit --files=extensions/amp-my-element/0.1/test/test-amp-my-element.js -- ## Type checking We use Closure Compiler to perform type checking. Please see -[Annotating JavaScript for the Closure -Compiler](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler) -and existing AMP code for examples of how to add type annotations to -your code. The following command should be run to ensure no type -violations are introduced by your extension. +[Annotating JavaScript for the Closure Compiler](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler) +and existing AMP code for examples of how to add type annotations to your code. +The following command should be run to ensure no type violations are introduced +by your extension. ```shell $ gulp check-types diff --git a/contributing/component-validator-rules.md b/contributing/component-validator-rules.md index 10230326e14b..c059a60c44ed 100644 --- a/contributing/component-validator-rules.md +++ b/contributing/component-validator-rules.md @@ -1,26 +1,27 @@ # Contributing Validator Rules for an AMP Extended Component -This doc describes how to create a basic validator ruleset for a new [AMP -Extended Component](https://amp.dev/documentation/components/). It -does not describe every possible validator feature, but rather goes over some -of the most common rules used when creating a new AMP Extended Component. +This doc describes how to create a basic validator ruleset for a new +[AMP Extended Component](https://amp.dev/documentation/components/). It does not +describe every possible validator feature, but rather goes over some of the most +common rules used when creating a new AMP Extended Component. ## Getting Started Before writing any of your `.protoascii` or `validator-*.html` files, please [see the Installation and Usage sections of the AMP Validator](https://github.com/ampproject/amphtml/blob/master/validator/README.md). -This repo uses a [python script](https://github.com/ampproject/amphtml/blob/master/validator/build.py) to run golden tests using the AMP validator. -Thus it is a good idea to ensure, -that your development environment is configured correctly, -before writing new tests to avoid any confusion. +This repo uses a +[python script](https://github.com/ampproject/amphtml/blob/master/validator/build.py) +to run golden tests using the AMP validator. Thus it is a good idea to ensure, +that your development environment is configured correctly, before writing new +tests to avoid any confusion. ## Example As a concrete example, imagine you are creating an extended component that -displays an image of a cat inside an AMP document. This extended component -loads one of a set of 3 different pre-built cat images, so that the user -doesn't need to host the images on their server. Each image has a cat name: +displays an image of a cat inside an AMP document. This extended component loads +one of a set of 3 different pre-built cat images, so that the user doesn't need +to host the images on their server. Each image has a cat name: - Oscar - Chloe @@ -38,20 +39,19 @@ Common usage of this extended component might look like: Your first step will be writing the extended component JavaScript code. Place this code in the amphtml src tree at the location of -`amphtml/extensions/amp-cat/0.1/`. This document only describes how to -specify validation rules for an extended component - it does not cover -implementing its runtime behavior. For the latter, see the codelab [Creating -your first AMP -Component](https://codelabs.developers.google.com/codelabs/creating-your-first-amp-component/). +`amphtml/extensions/amp-cat/0.1/`. This document only describes how to specify +validation rules for an extended component - it does not cover implementing its +runtime behavior. For the latter, see the codelab +[Creating your first AMP Component](https://codelabs.developers.google.com/codelabs/creating-your-first-amp-component/). ## Validation Rules -Once you have built the extended component JavaScript, you are ready to submit validator -rules. You may do this in the same Pull Request, or a later Pull Request for -simplicity. +Once you have built the extended component JavaScript, you are ready to submit +validator rules. You may do this in the same Pull Request, or a later Pull +Request for simplicity. -You will be creating a rules file as well as two test files. The paths for -these files, using the `` example above, would be: +You will be creating a rules file as well as two test files. The paths for these +files, using the `` example above, would be: **Rules File** @@ -144,8 +144,7 @@ Let's see it broken down: # ``` -This is the AMP HTML license statement required at the top of every AMP -file. +This is the AMP HTML license statement required at the top of every AMP file. ### amp-cat extended component @@ -162,11 +161,10 @@ to validate a tag that looks something like the following: html_format: AMP; ``` -This tells the validator that this tag -should be valid in AMP format documents. Tags can also be valid in `AMP4ADS` -format documents, if the tag should be used in an ad format. If you are unsure, -leave the tag as an `AMP` format tag only for now. Additional formats can be -added later. +This tells the validator that this tag should be valid in AMP format documents. +Tags can also be valid in `AMP4ADS` format documents, if the tag should be used +in an ad format. If you are unsure, leave the tag as an `AMP` format tag only +for now. Additional formats can be added later. ```js tag_name: 'SCRIPT'; @@ -184,8 +182,8 @@ The following fields describe the HTML Tag attributes we expect for this The `extension_spec` field indicates that this ` ``` -While it is a requirement that the same version is used for the runtime and extension scripts, requesting **lts** is valid AMP. It will get the same cache benefits as the stable release channel. - -**Important**: Publishers using the **lts** release channel should be careful when using newly introduced features. Because of the longer cycle, the **lts** release may be as much as six weeks behind the `HEAD` of [`ampproject/amphtml`](https://github.com/ampproject/amphtml). See the section on [determining if your change is in a release](https://github.com/ampproject/amphtml/blob/master/contributing/release-schedule.md#Determining-if-your-change-is-in-a-release) to validate if a change will be ready with your chosen release cycle. +While it is a requirement that the same version is used for the runtime and +extension scripts, requesting **lts** is valid AMP. It will get the same cache +benefits as the stable release channel. + +**Important**: Publishers using the **lts** release channel should be careful +when using newly introduced features. Because of the longer cycle, the **lts** +release may be as much as six weeks behind the `HEAD` of +[`ampproject/amphtml`](https://github.com/ampproject/amphtml). See the section +on +[determining if your change is in a release](https://github.com/ampproject/amphtml/blob/master/contributing/release-schedule.md#Determining-if-your-change-is-in-a-release) +to validate if a change will be ready with your chosen release cycle. diff --git a/contributing/release-schedule.md b/contributing/release-schedule.md index 49419337ba65..d9403a0ba16e 100644 --- a/contributing/release-schedule.md +++ b/contributing/release-schedule.md @@ -10,118 +10,244 @@ - [AMP Beta Channel (Beta)](#amp-beta-channel-beta) - [Release Freezes](#release-freezes) -A new release of AMP is pushed to all AMP pages every week on Tuesday. **Once a change in AMP is merged into the master branch of the amphtml repository, it will typically take 1-2 weeks for the change be live for all users.** +A new release of AMP is pushed to all AMP pages every week on Tuesday. **Once a +change in AMP is merged into the master branch of the amphtml repository, it +will typically take 1-2 weeks for the change be live for all users.** ## Release Channels -The AMP runtime and extensions are provided through a variety of different _release channels_. Each channel serves a purpose for developers and for the AMP HTML Project itself. See the [release cadence section](#release-cadence) for a more detailed breakdown of how and when code from the [`ampproject/amphtml`](https://github.com/ampproject/amphtml) repository makes it into release builds. +The AMP runtime and extensions are provided through a variety of different +_release channels_. Each channel serves a purpose for developers and for the AMP +HTML Project itself. See the [release cadence section](#release-cadence) for a +more detailed breakdown of how and when code from the +[`ampproject/amphtml`](https://github.com/ampproject/amphtml) repository makes +it into release builds. -To determine if a PR has been included in any of the following release channels, look for the GitHub labels _PR Use: In Canary_, _PR Use: In Production_, or _PR Use: In LTS_ (see the section on [determining if your change is in a release](#Determining-if-your-change-is-in-a-release) for more details). +To determine if a PR has been included in any of the following release channels, +look for the GitHub labels _PR Use: In Canary_, _PR Use: In Production_, or _PR +Use: In LTS_ (see the section on +[determining if your change is in a release](#Determining-if-your-change-is-in-a-release) +for more details). ### Weekly -The _weekly_ release channels are considered to be the primary "evergreen" release channels. A green build from the `master` branch is used to build the **experimental** and **beta** release channels; the **beta** release from the previous week is promoted to the **stable** release channel (see the [detailed schedule](#detailed-schedule)). - -There are two sets of build configurations used in creating release builds: the _canary_ configuration and the _production_ configuration. The **experimental** and **beta** release channels are built off of the same commit. However, the **experimental** channel uses the _canary_ configuration while the **beta** channel uses the _production_ configuration. The _canary_ configuration enables experimental components and features that may be turned off in _production_. It is possible to opt into the **experimental** or **beta** channels via the [experiments page](https://cdn.ampproject.org/experiments.html). - -The **stable** release channel is built with the _production_ configuration and served to most AMP traffic. Since the **beta** release channel is also built from the _production_ configuration, it represents the exact build which will become **stable** the following week (modulo the possibility of cherry-picks; see [Contributing Code](https://github.com/ampproject/amphtml/blob/master/contributing/contributing-code.md#Cherry-picks)). +The _weekly_ release channels are considered to be the primary "evergreen" +release channels. A green build from the `master` branch is used to build the +**experimental** and **beta** release channels; the **beta** release from the +previous week is promoted to the **stable** release channel (see the +[detailed schedule](#detailed-schedule)). + +There are two sets of build configurations used in creating release builds: the +_canary_ configuration and the _production_ configuration. The **experimental** +and **beta** release channels are built off of the same commit. However, the +**experimental** channel uses the _canary_ configuration while the **beta** +channel uses the _production_ configuration. The _canary_ configuration enables +experimental components and features that may be turned off in _production_. It +is possible to opt into the **experimental** or **beta** channels via the +[experiments page](https://cdn.ampproject.org/experiments.html). + +The **stable** release channel is built with the _production_ configuration and +served to most AMP traffic. Since the **beta** release channel is also built +from the _production_ configuration, it represents the exact build which will +become **stable** the following week (modulo the possibility of cherry-picks; +see +[Contributing Code](https://github.com/ampproject/amphtml/blob/master/contributing/contributing-code.md#Cherry-picks)). ### Long-Term Stable (lts) -The **lts** release channel provides a previous **stable** build for one-month intervals. Approximately monthly, the current **stable** release is promoted to **lts**. This channel is not recommended for all AMP publishers. It is provided so that publishers who wish to perform a QA cycle on their website less frequently may do so by opting specific web pages into the **lts** channel (see the [**lts** readme](https://github.com/ampproject/amphtml/blob/master/contributing/lts-release.md)). - -Important: Publishers using the **lts** release channel should not use newly introduced features. Because of the longer cycle, the **lts** release may be as much as seven weeks behind the `HEAD` of [`ampproject/amphtml`](https://github.com/ampproject/amphtml). See the section on [determining if your change is in a release](#Determining-if-your-change-is-in-a-release) to validate if a change will be ready with your chosen release cycle. +The **lts** release channel provides a previous **stable** build for one-month +intervals. Approximately monthly, the current **stable** release is promoted to +**lts**. This channel is not recommended for all AMP publishers. It is provided +so that publishers who wish to perform a QA cycle on their website less +frequently may do so by opting specific web pages into the **lts** channel (see +the +[**lts** readme](https://github.com/ampproject/amphtml/blob/master/contributing/lts-release.md)). + +Important: Publishers using the **lts** release channel should not use newly +introduced features. Because of the longer cycle, the **lts** release may be as +much as seven weeks behind the `HEAD` of +[`ampproject/amphtml`](https://github.com/ampproject/amphtml). See the section +on +[determining if your change is in a release](#Determining-if-your-change-is-in-a-release) +to validate if a change will be ready with your chosen release cycle. ## Determining if your change is in a release -[_Type: Release_ GitHub issues](https://github.com/ampproject/amphtml/labels/Type%3A%20Release) are used to track the status of current and past releases; from the initial cut, to testing via **experimantal**/**beta** channels, to eventual release via the **stable** and **lts** channels. Announcements about releases are made on the [AMP Slack #release channel](https://amphtml.slack.com/messages/C4NVAR0H3/) ([sign up for Slack](https://bit.ly/amp-slack-signup)). +[_Type: Release_ GitHub issues](https://github.com/ampproject/amphtml/labels/Type%3A%20Release) +are used to track the status of current and past releases; from the initial cut, +to testing via **experimantal**/**beta** channels, to eventual release via the +**stable** and **lts** channels. Announcements about releases are made on the +[AMP Slack #release channel](https://amphtml.slack.com/messages/C4NVAR0H3/) +([sign up for Slack](https://bit.ly/amp-slack-signup)). You can determine what changes are in a given build using one of the following: -- The [_Type: Release_ GitHub issues](https://github.com/ampproject/amphtml/labels/Type%3A%20Release) for each release build will include a link to the specific [release page](https://github.com/ampproject/amphtml/releases) listing the changes contained in that release. -- The [_PR Use: In Canary_](https://github.com/ampproject/amphtml/issues?utf8=%E2%9C%93&q=label%3A%22PR%20use%3A%20In%20Canary%22), [_PR Use: In Production_](https://github.com/ampproject/amphtml/issues?utf8=%E2%9C%93&q=label%3A%22PR%20use%3A%20In%20Production%22), and [_PR Use: In LTS_](https://github.com/ampproject/amphtml/issues?utf8=%E2%9C%93&q=label%3A%22PR%20use%3A%20In%20LTS%22) labels are added to PRs when they've made it into a _weekly_ or **lts** build. There may be a delay between when the build is created and when the label is added. - -> Note: These labels still use legacy release names. They will be renamed soon to reflect the new release channel names (**beta** and **stable**). +- The + [_Type: Release_ GitHub issues](https://github.com/ampproject/amphtml/labels/Type%3A%20Release) + for each release build will include a link to the specific + [release page](https://github.com/ampproject/amphtml/releases) listing the + changes contained in that release. +- The + [_PR Use: In Canary_](https://github.com/ampproject/amphtml/issues?utf8=%E2%9C%93&q=label%3A%22PR%20use%3A%20In%20Canary%22), + [_PR Use: In Production_](https://github.com/ampproject/amphtml/issues?utf8=%E2%9C%93&q=label%3A%22PR%20use%3A%20In%20Production%22), + and + [_PR Use: In LTS_](https://github.com/ampproject/amphtml/issues?utf8=%E2%9C%93&q=label%3A%22PR%20use%3A%20In%20LTS%22) + labels are added to PRs when they've made it into a _weekly_ or **lts** build. + There may be a delay between when the build is created and when the label is + added. + +> Note: These labels still use legacy release names. They will be renamed soon +> to reflect the new release channel names (**beta** and **stable**). ## Release Cadence We are intentionally cautious with our release cadence. -In determining how often we should push new versions of AMP to everyone, we have to weigh many factors including: +In determining how often we should push new versions of AMP to everyone, we have +to weigh many factors including: - stability for the millions of sites/billions of pages built using AMP - cache busting that might happen when we push a new version - the desire to get new features out quickly -After considering all of these factors we have arrived at the 1-2 week push cycle. Thus far we have found this to be a reasonable compromise, but we will continue to evaluate all of these factors and may make changes in the future. +After considering all of these factors we have arrived at the 1-2 week push +cycle. Thus far we have found this to be a reasonable compromise, but we will +continue to evaluate all of these factors and may make changes in the future. ### Detailed schedule -We try to stick to this schedule as closely as possible, though complications may cause delays. You can track the latest status about any release in the [_Type: Release_ GitHub issues](https://github.com/ampproject/amphtml/labels/Type%3A%20Release) and the [AMP Slack #release channel](https://amphtml.slack.com/messages/C4NVAR0H3/) ([sign up for Slack](https://bit.ly/amp-slack-signup)). - -- Tuesday @ [11am Pacific](https://www.google.com/search?q=11am+pacific+in+current+time+zone): new **experimental** and **beta** release builds are created from the [latest master build that passes all of our tests](https://travis-ci.org/ampproject/amphtml/branches) and are pushed to users of AMP who opted into the [AMP Dev Channel](#amp-dev-channel) or [AMP Beta Channel](#amp-beta-channel), respectively. -- Wednesday: we check bug reports for _Dev Channel_ and _Beta Channel_ users and if everything looks fine, we push the **beta** to 1% of AMP pages -- Thursday-Monday: we continue to monitor error rates and bug reports for _Dev Channel_ and _Beta Channel_ users and the 1% of pages with the **experimental**/**beta** builds -- Tuesday the following week: the **beta** build is fully promoted to **stable** (i.e. all AMP pages will now use this build) +We try to stick to this schedule as closely as possible, though complications +may cause delays. You can track the latest status about any release in the +[_Type: Release_ GitHub issues](https://github.com/ampproject/amphtml/labels/Type%3A%20Release) +and the +[AMP Slack #release channel](https://amphtml.slack.com/messages/C4NVAR0H3/) +([sign up for Slack](https://bit.ly/amp-slack-signup)). + +- Tuesday @ + [11am Pacific](https://www.google.com/search?q=11am+pacific+in+current+time+zone): + new **experimental** and **beta** release builds are created from the + [latest master build that passes all of our tests](https://travis-ci.org/ampproject/amphtml/branches) + and are pushed to users of AMP who opted into the + [AMP Dev Channel](#amp-dev-channel) or [AMP Beta Channel](#amp-beta-channel), + respectively. +- Wednesday: we check bug reports for _Dev Channel_ and _Beta Channel_ users and + if everything looks fine, we push the **beta** to 1% of AMP pages +- Thursday-Monday: we continue to monitor error rates and bug reports for _Dev + Channel_ and _Beta Channel_ users and the 1% of pages with the + **experimental**/**beta** builds +- Tuesday the following week: the **beta** build is fully promoted to **stable** + (i.e. all AMP pages will now use this build) ### AMP Dev Channel (Experimental) -The _AMP Dev Channel_ is a way to opt a browser into using the **experimental** release build of the AMP JS libraries. The _Dev Channel_ **may be less stable** and it may contain features not yet available to all users. +The _AMP Dev Channel_ is a way to opt a browser into using the **experimental** +release build of the AMP JS libraries. The _Dev Channel_ **may be less stable** +and it may contain features not yet available to all users. Opting into the _Dev Channel_ is intended for: - testing and playing with new features not yet available to all users -- using in Quality Assurance (QA) to ensure that your site is compatible with upcoming features of AMP that are still under development - -When you opt into the _AMP Dev Channel_ you are only affecting the AMP JS libraries in your browser; there is no way to force visitors to your site to use the _AMP Dev Channel_ version of AMP. - -To opt your browser into the _AMP Dev Channel_, go to [the AMP experiments page](https://cdn.ampproject.org/experiments.html) and activate the "AMP Dev Channel" experiment. Please subscribe to our [low-volume announcements](https://groups.google.com/forum/#!forum/amphtml-announce) mailing list to get notified about important/breaking changes about AMP. - -**If you find an issue that appears to only occur in the Dev Channel version of AMP**: - -- please [file an issue](https://github.com/ampproject/amphtml/issues/new) with a description of the problem - - include a note that the problem is new to the Dev Channel build so that it can be properly prioritized +- using in Quality Assurance (QA) to ensure that your site is compatible with + upcoming features of AMP that are still under development + +When you opt into the _AMP Dev Channel_ you are only affecting the AMP JS +libraries in your browser; there is no way to force visitors to your site to use +the _AMP Dev Channel_ version of AMP. + +To opt your browser into the _AMP Dev Channel_, go to +[the AMP experiments page](https://cdn.ampproject.org/experiments.html) and +activate the "AMP Dev Channel" experiment. Please subscribe to our +[low-volume announcements](https://groups.google.com/forum/#!forum/amphtml-announce) +mailing list to get notified about important/breaking changes about AMP. + +**If you find an issue that appears to only occur in the Dev Channel version of +AMP**: + +- please [file an issue](https://github.com/ampproject/amphtml/issues/new) with + a description of the problem + - include a note that the problem is new to the Dev Channel build so that it + can be properly prioritized - include a URL to a page that reproduces the problem -- ping the [AMP Slack #release channel](https://amphtml.slack.com/messages/C4NVAR0H3/) ([sign up for Slack](https://bit.ly/amp-slack-signup)) with the issue you filed so we can delay the push of the Dev Channel version to production if needed +- ping the + [AMP Slack #release channel](https://amphtml.slack.com/messages/C4NVAR0H3/) + ([sign up for Slack](https://bit.ly/amp-slack-signup)) with the issue you + filed so we can delay the push of the Dev Channel version to production if + needed ### AMP Beta Channel (Beta) -The _AMP Beta Channel_ is a way to opt a browser into using the **beta** release build of the AMP JS libraries that will be promoted to **stable** during the subsequent release cycle (typically, a week later). It is similar to the _Dev Channel_ described above, but it will not contain the experimental features that are still under development. +The _AMP Beta Channel_ is a way to opt a browser into using the **beta** release +build of the AMP JS libraries that will be promoted to **stable** during the +subsequent release cycle (typically, a week later). It is similar to the _Dev +Channel_ described above, but it will not contain the experimental features that +are still under development. Opting into the _Beta Channel_ is intended for: -- testing and playing with the version of the AMP runtime that will be released soon -- using in Quality Assurance (QA) to ensure that your site is compatible with the next version of AMP +- testing and playing with the version of the AMP runtime that will be released + soon +- using in Quality Assurance (QA) to ensure that your site is compatible with + the next version of AMP -Similar to the _Dev Channel_, when you opt into the _AMP Beta Channel_ you are only affecting the AMP JS libraries in your browser; there is no way to force visitors to your site to use the _AMP Beta Channel_ version of AMP. +Similar to the _Dev Channel_, when you opt into the _AMP Beta Channel_ you are +only affecting the AMP JS libraries in your browser; there is no way to force +visitors to your site to use the _AMP Beta Channel_ version of AMP. -To opt your browser into the _AMP Beta Channel_, go to [the AMP experiments page](https://cdn.ampproject.org/experiments.html) and activate the "AMP RC Channel" experiment. Please subscribe to our [low-volume announcements](https://groups.google.com/forum/#!forum/amphtml-announce) mailing list to get notified about important/breaking changes about AMP. +To opt your browser into the _AMP Beta Channel_, go to +[the AMP experiments page](https://cdn.ampproject.org/experiments.html) and +activate the "AMP RC Channel" experiment. Please subscribe to our +[low-volume announcements](https://groups.google.com/forum/#!forum/amphtml-announce) +mailing list to get notified about important/breaking changes about AMP. -> Note: "RC" refers to the term "Release Candidate", which was the previous name for the **beta** release channel. +> Note: "RC" refers to the term "Release Candidate", which was the previous name +> for the **beta** release channel. -**If you find an issue that appears to only occur in the _Beta Channel_ version of AMP**: +**If you find an issue that appears to only occur in the _Beta Channel_ version +of AMP**: -- please [file an issue](https://github.com/ampproject/amphtml/issues/new) with a description of the problem - - include a note that the problem is new to the _Beta Channel_ build so that it can be properly prioritized +- please [file an issue](https://github.com/ampproject/amphtml/issues/new) with + a description of the problem + - include a note that the problem is new to the _Beta Channel_ build so that + it can be properly prioritized - include a URL to a page that reproduces the problem -- ping the [AMP Slack #release channel](https://amphtml.slack.com/messages/C4NVAR0H3/) ([sign up for Slack](https://bit.ly/amp-slack-signup)) with the issue you filed so we can delay the push of the _Beta Channel_ version to production if needed +- ping the + [AMP Slack #release channel](https://amphtml.slack.com/messages/C4NVAR0H3/) + ([sign up for Slack](https://bit.ly/amp-slack-signup)) with the issue you + filed so we can delay the push of the _Beta Channel_ version to production if + needed ## Release Freezes -There are occasions when we will skip a release of AMP to production, known as a release freeze. +There are occasions when we will skip a release of AMP to production, known as a +release freeze. If a one week release freeze is announced for Week N: -- The previous week's release build remains in **experimental**/**beta** for an extra week, i.e. the release cut in Week N-1 is not pushed to **stable** in Week N as would normally be the case. Instead, it will be pushed to **stable** in Week N+1. +- The previous week's release build remains in **experimental**/**beta** for an + extra week, i.e. the release cut in Week N-1 is not pushed to **stable** in + Week N as would normally be the case. Instead, it will be pushed to **stable** + in Week N+1. - A new release build is _not_ made in the freeze week (Week N). -- The normal schedule will resume in Week N+1, i.e. **experimental**/**beta** are cut in Week N+1 and promoted to **stable** in Week N+2. +- The normal schedule will resume in Week N+1, i.e. **experimental**/**beta** + are cut in Week N+1 and promoted to **stable** in Week N+2. A release freeze may happen due to: -- Times when there are not enough people available to push the AMP release to **stable** and monitor it. Currently most of the people performing AMP releases are based in the United States, so this will usually be the weeks of the major US holidays of Independence Day (July 4), Thanksgiving (fourth Thursday in November), Christmas (25 December) and New Year's Eve/Day (December 31/January 1). -- An emergency situation, such as a security or privacy issue as determined by the [Technical Steering Committee (TSC)](https://github.com/ampproject/meta-tsc) or the people performing the release. -- Other situations when stability of the codebase is deemed to be particularly important as determined by the TSC. - -In all cases except emergencies the release freezes will be announced at least one month in advance. - -Note that unless otherwise announced a release freeze does not imply a code freeze. Code may still be written, reviewed and merged during a release freeze. +- Times when there are not enough people available to push the AMP release to + **stable** and monitor it. Currently most of the people performing AMP + releases are based in the United States, so this will usually be the weeks of + the major US holidays of Independence Day (July 4), Thanksgiving (fourth + Thursday in November), Christmas (25 December) and New Year's Eve/Day + (December 31/January 1). +- An emergency situation, such as a security or privacy issue as determined by + the + [Technical Steering Committee (TSC)](https://github.com/ampproject/meta-tsc) + or the people performing the release. +- Other situations when stability of the codebase is deemed to be particularly + important as determined by the TSC. + +In all cases except emergencies the release freezes will be announced at least +one month in advance. + +Note that unless otherwise announced a release freeze does not imply a code +freeze. Code may still be written, reviewed and merged during a release freeze. diff --git a/contributing/writing-css.md b/contributing/writing-css.md index deb8eacc4996..28183a6d6c92 100644 --- a/contributing/writing-css.md +++ b/contributing/writing-css.md @@ -16,19 +16,21 @@ ## Who should read this doc? -Do you contribute changes to the AMP Runtime or add/modify AMP extensions? If you answer yes, then you should definitely read this document. +Do you contribute changes to the AMP Runtime or add/modify AMP extensions? If +you answer yes, then you should definitely read this document. -Do you write solutions on top of the amp library (ampstart/ABE), this may be a good read for -you. +Do you write solutions on top of the amp library (ampstart/ABE), this may be a +good read for you. ## What is Specificity? -Specificity is the means by which browsers decide which CSS property values are the most -relevant to an element and, therefore, will be applied. Specificity is based on the matching rules -which are composed of different sorts of CSS selectors. +Specificity is the means by which browsers decide which CSS property values are +the most relevant to an element and, therefore, will be applied. Specificity is +based on the matching rules which are composed of different sorts of CSS +selectors. -A selector is something which can identify/select an element or a group of elements and apply a -list of properties to all the selected elements. +A selector is something which can identify/select an element or a group of +elements and apply a list of properties to all the selected elements. ### Example: CSS selectors @@ -43,73 +45,89 @@ html > body div#pagewrap ul#summer-drinks > li.favorite #summer-drinks::after ``` -A selector can contain a class, id, pseudo elements, psuedo classes , :not(), and a combination -of any of these and many more. For a comprehensive list of all CSS selectors, see https://developer.mozilla.org/en-US/docs/Web/CSS/Reference#Selectors. +A selector can contain a class, id, pseudo elements, psuedo classes , :not(), +and a combination of any of these and many more. For a comprehensive list of all +CSS selectors, see +https://developer.mozilla.org/en-US/docs/Web/CSS/Reference#Selectors. -In general, the order of the CSS selectors do not affect which rules get applied to your CSS, -unless the selectors have the same specificity and apply to at least one element in common. -Well-written CSS will work perfectly fine even when the selectors are re-ordered (for example, when reordering imports in a css file). In the real world, it's hard to achieve this, especially -when we import CSS via gulp or third-party CSS (which can change at any time). +In general, the order of the CSS selectors do not affect which rules get applied +to your CSS, unless the selectors have the same specificity and apply to at +least one element in common. Well-written CSS will work perfectly fine even when +the selectors are re-ordered (for example, when reordering imports in a css +file). In the real world, it's hard to achieve this, especially when we import +CSS via gulp or third-party CSS (which can change at any time). ### How to calculate Specificity -Visit the [CSS Tricks: Specifics on CSS Specificity](https://css-tricks.com/specifics-on-css-specificity/) which explains specificity in very simple terms and shows how specificity is computed (it's very short and understandable). +Visit the +[CSS Tricks: Specifics on CSS Specificity](https://css-tricks.com/specifics-on-css-specificity/) +which explains specificity in very simple terms and shows how specificity is +computed (it's very short and understandable). -To compute specificity, use this online calculator: https://specificity.keegan.st/ +To compute specificity, use this online calculator: +https://specificity.keegan.st/ ## Writing CSS in AMP Runtime or Extensions ### Creating a new Selector -1. Keep the specificity as low as possible; the Selector properties should be easily - overridable (using maybe a single id or class-name, without having to repeat a complex - selector). -2. Try to write selectors by using tag names and attributes; class names that get added after - build GET FOUC. [FOUC (Flash Of Unstyled Content)](#fouc) is a really bad UX. Use caution - and best effort to STAY AWAY from using elements/classes that are a result of - BUILDing in the CSS. +1. Keep the specificity as low as possible; the Selector properties should be + easily overridable (using maybe a single id or class-name, without having to + repeat a complex selector). +2. Try to write selectors by using tag names and attributes; class names that + get added after build GET FOUC. [FOUC (Flash Of Unstyled Content)](#fouc) is + a really bad UX. Use caution and best effort to STAY AWAY from using + elements/classes that are a result of BUILDing in the CSS. - A good example would be amp-selector. - - A bad example would be amp-accordion (See the [Case Studies](#case-studies) below). + - A bad example would be amp-accordion (See the [Case Studies](#case-studies) + below). 3. Keep the Selector as simple as possible and ensure it's readable. ### Modifying an existing Selector -This is a bit more tricky than creating a new selector (with completely new properties). +This is a bit more tricky than creating a new selector (with completely new +properties). -AMP is a versioned library that a lot of websites use. You might ask yourself, "But I am only changing CSS, how can -this break AMP?". Well, you can! All it takes to break backwards compatibility is replacing a selector with another +AMP is a versioned library that a lot of websites use. You might ask yourself, +"But I am only changing CSS, how can this break AMP?". Well, you can! All it +takes to break backwards compatibility is replacing a selector with another selector that has higher specificity. 1. Do not change the specificity of a selector, if possible. -2. If a new property (like font-size: 12px;) is being added, it is okay to add a new selector. -3. If an existing property is being shifted around between existing selectors, make sure the - properties always move from higher specificity to lower specificity. -4. DO NOT move properties to a selector with high specificity at any cost! This is a - **BREAKING change**. +2. If a new property (like font-size: 12px;) is being added, it is okay to add a + new selector. +3. If an existing property is being shifted around between existing selectors, + make sure the properties always move from higher specificity to lower + specificity. +4. DO NOT move properties to a selector with high specificity at any cost! This + is a **BREAKING change**. 5. Remember there are 2 types of properties: - Overridable - Non-overridable: The ones suffixed with `!important` - - These properties can be shifted around easily. However, BE CAUTIOUS - when you suffix an existing property with `!important` because this is ALWAYS + - These properties can be shifted around easily. However, BE CAUTIOUS when + you suffix an existing property with `!important` because this is ALWAYS going to BREAK backwards compatibility (but could fix issues). - - Always add `!important` during the first pass, and plan for it during design or - early implementation phases. + - Always add `!important` during the first pass, and plan for it during + design or early implementation phases. ### FOUC -When building extensions, you should always be aware of things that could cause FOUC (Flash Of Unstyled -Content). This happens when (if) the extension is built very late and the extension’s CSS is -dependent on DOM Structure changes (addition of a class or a tag or may be restructuring the -DOM itself) that happens as a result of building the extension. +When building extensions, you should always be aware of things that could cause +FOUC (Flash Of Unstyled Content). This happens when (if) the extension is built +very late and the extension’s CSS is dependent on DOM Structure changes +(addition of a class or a tag or may be restructuring the DOM itself) that +happens as a result of building the extension. -While it is not completely possible to avoid this, ideally it would be better to write selectors that -are independent of BUILD outcomes. This ensures that there is no repaints (at least in the initial -state). +While it is not completely possible to avoid this, ideally it would be better to +write selectors that are independent of BUILD outcomes. This ensures that there +is no repaints (at least in the initial state). -One way to avoid re-layouts after BUILD is to separate out all the CSS properties into `in` and -`out` properties. "In" styles are unlikely to cause a lot of FOUC or any at all. "Out" styles may cause FOUC and -we should probably phrase it as "not allowed". A good example is padding vs margin of the -element itself. It's totally fine to change padding during build, but a huge no-no for margin. +One way to avoid re-layouts after BUILD is to separate out all the CSS +properties into `in` and `out` properties. "In" styles are unlikely to cause a +lot of FOUC or any at all. "Out" styles may cause FOUC and we should probably +phrase it as "not allowed". A good example is padding vs margin of the element +itself. It's totally fine to change padding during build, but a huge no-no for +margin. ### Rule of thumb @@ -135,11 +153,12 @@ amp-selector:not([disabled]) [option][selected]:not Why is it bad? -1. It's a super high specificity selector, that is, it's very hard to override using a single class name or id. +1. It's a super high specificity selector, that is, it's very hard to override + using a single class name or id. 2. There are no comments, and it's almost unreadable. -The only good part about this CSS is that it completely avoids FOUC by targeting tags and attributes, and -not depending on the build outcome. +The only good part about this CSS is that it completely avoids FOUC by targeting +tags and attributes, and not depending on the build outcome. **Improving the CSS** @@ -155,7 +174,8 @@ amp-selector[disabled] [selected] { } ``` -Fixing PR: https://github.com/ampproject/amphtml/commit/e12deb125bc0bed16d33481e0c +Fixing PR: +https://github.com/ampproject/amphtml/commit/e12deb125bc0bed16d33481e0c ### AMP Accordion CSS changes broke specificity @@ -176,13 +196,15 @@ Fixing PR: https://github.com/ampproject/amphtml/commit/e12deb125bc0bed16d33481e +} ``` -- Breaking change: https://github.com/ampproject/amphtml/commit/f2a361651b4b4d1d484c6cd9502c895695545d +- Breaking change: + https://github.com/ampproject/amphtml/commit/f2a361651b4b4d1d484c6cd9502c895695545d - GH Issue : https://github.com/ampproject/amphtml/issues/10224 - Partial Rollback: https://github.com/ampproject/amphtml/pull/10225 -The lesson learnt here is that even though the breaking CSS was a good change (it fixed the FOUC -due to the class introduced at BUILD), it moved properties from a selector with LOWER -specificity to HIGHER specificity, which breaks backward compatibility. +The lesson learnt here is that even though the breaking CSS was a good change +(it fixed the FOUC due to the class introduced at BUILD), it moved properties +from a selector with LOWER specificity to HIGHER specificity, which breaks +backward compatibility. ## Reading material diff --git a/examples/amphtml-ads/README.md b/examples/amphtml-ads/README.md index df803593b1f7..5031283b5ed2 100644 --- a/examples/amphtml-ads/README.md +++ b/examples/amphtml-ads/README.md @@ -1,6 +1,7 @@ -Files under this folder are mainly one of the 2 types, differentiated -by their file name patterns: +Files under this folder are mainly one of the 2 types, differentiated by their +file name patterns: -- `*.a4a.html`: are AMPHTML ads, which need to be viewed through - one of the supported [AMPHTML ads envelopes](../../../../contributing/TESTING.md#a4a-envelope-a4a-a4a-3p). +- `*.a4a.html`: are AMPHTML ads, which need to be viewed through one of the + supported + [AMPHTML ads envelopes](../../../../contributing/TESTING.md#a4a-envelope-a4a-a4a-3p). - `*.host.html`: are regular HTML pages that load AMPHTML ads. diff --git a/examples/metadata-examples/README.md b/examples/metadata-examples/README.md index 43d47d99c69c..d9ce076ee143 100644 --- a/examples/metadata-examples/README.md +++ b/examples/metadata-examples/README.md @@ -1,10 +1,12 @@ -This directory contains examples of different types of pages written with AMP marked up -with standard schema.org markup in two different formats: JSON-LD and microdata. +This directory contains examples of different types of pages written with AMP +marked up with standard schema.org markup in two different formats: JSON-LD and +microdata. Though they are effectively equivalent, we generally recommend JSON-LD as it more easily pairs with AMP HTML Components. -The fields used and their types listed in each example should be considered best practices, but different platforms may have other requirements for inclusion. +The fields used and their types listed in each example should be considered best +practices, but different platforms may have other requirements for inclusion.
   article-json-ld.amp.html         - JSON-LD   structured data markup format for Articles
diff --git a/extensions/README.md b/extensions/README.md
index 2385085a88bf..43fcda6e2b17 100644
--- a/extensions/README.md
+++ b/extensions/README.md
@@ -4,10 +4,11 @@ AMP Extensions are either extended components or extended templates.
 
 ## AMP HTML Extended Components
 
-Extended components must be explicitly included into the document as custom elements.
+Extended components must be explicitly included into the document as custom
+elements.
 
-For example, to include a YouTube video in your page
-include the following script in the ``:
+For example, to include a YouTube video in your page include the following
+script in the ``:
 
 ```html
 ` tag.
 - Unlike general AMP, `
 
 
-The `amp-date-countdown` provides countdown time data that you can render in your AMP page. By providing specific [attributes](#attributes) in the `amp-date-countdown` tag, the `amp-date-countdown` extension returns a list of time parameters, which you can pass to an `amp-mustache` template for rendering. Refer to the [ list below for each returned time parameter](#returned-time-parameters).
+The `amp-date-countdown` provides countdown time data that you can render in
+your AMP page. By providing specific [attributes](#attributes) in the
+`amp-date-countdown` tag, the `amp-date-countdown` extension returns a list of
+time parameters, which you can pass to an `amp-mustache` template for rendering.
+Refer to the
+[ list below for each returned time parameter](#returned-time-parameters).
 
 ### Example
 
@@ -97,7 +103,8 @@ This table lists the format you can specify in your Mustache template:
 
 #### Samples of formatted values
 
-This table provides examples of formatted values specified in a Mustache template, and a sample of what the output:
+This table provides examples of formatted values specified in a Mustache
+template, and a sample of what the output:
 
 | Format                                          | Sample Output                        | Remarks                |
 | ----------------------------------------------- | ------------------------------------ | ---------------------- |
@@ -111,7 +118,8 @@ This table provides examples of formatted values specified in a Mustache templat
 
 ## Attributes
 
-You must specify at least one of these required attributes: `end-date`, `timeleft-ms`, `timestamp-ms`, `timestamp-seconds`.
+You must specify at least one of these required attributes: `end-date`,
+`timeleft-ms`, `timestamp-ms`, `timestamp-seconds`.
 
 ##### end-date
 
@@ -119,28 +127,36 @@ An ISO formatted date to count down to. For example, `2020-06-01T00:00:00+08:00`
 
 ##### timestamp-ms
 
-A POSIX epoch value in milliseconds; assumed to be UTC timezone. For example, `timestamp-ms="1521880470000"`.
+A POSIX epoch value in milliseconds; assumed to be UTC timezone. For example,
+`timestamp-ms="1521880470000"`.
 
 ##### timestamp-seconds
 
-A POSIX epoch value in seconds; assumed to be UTC timezone. For example, `timestamp-seconds="1521880470"`.
+A POSIX epoch value in seconds; assumed to be UTC timezone. For example,
+`timestamp-seconds="1521880470"`.
 
 ##### timeleft-ms
 
-A value in milliseconds left to be counting down. For example, 48 hours left `timeleft-ms="172800000"`.
+A value in milliseconds left to be counting down. For example, 48 hours left
+`timeleft-ms="172800000"`.
 
 ##### offset-seconds (optional)
 
-A positive or negative number that represents the number of seconds to add or subtract from the `end-date`. For example, `offset-seconds="60"` adds 60 seconds to the end-date.
+A positive or negative number that represents the number of seconds to add or
+subtract from the `end-date`. For example, `offset-seconds="60"` adds 60 seconds
+to the end-date.
 
 ##### when-ended (optional)
 
-Specifies whether to stop the timer when it reaches 0 seconds. The value can be set to `stop` (default) to indicate the timer to stop at 0 seconds and will not pass the final date or `continue` to indicate the timer should continue after reaching 0 seconds.
+Specifies whether to stop the timer when it reaches 0 seconds. The value can be
+set to `stop` (default) to indicate the timer to stop at 0 seconds and will not
+pass the final date or `continue` to indicate the timer should continue after
+reaching 0 seconds.
 
 ##### locale (optional)
 
-An internationalization language string for each timer unit. The default value is `en` (for English).
-Supported values:
+An internationalization language string for each timer unit. The default value
+is `en` (for English). Supported values:
 
 | Code  | Language            |
 | ----- | ------------------- |
@@ -163,14 +179,18 @@ Supported values:
 
 ##### biggest-unit (optional)
 
-Allows the `amp-date-countdown` component to calculate the time difference based on the specified `biggest-unit` value. For example, assume there are `50 days 10 hours` left, if the `biggest-unit` is set to `hours`, the result displays `1210 hours` left.
+Allows the `amp-date-countdown` component to calculate the time difference based
+on the specified `biggest-unit` value. For example, assume there are
+`50 days 10 hours` left, if the `biggest-unit` is set to `hours`, the result
+displays `1210 hours` left.
 
 - Supported values: `days`, `hours`, `minutes`, `seconds`
 - Default: `days`
 
 ## Events
 
-The `amp-date-countdown` component exposes the following event that you can use [AMP on-syntax to trigger](https://amp.dev/documentation/guides-and-tutorials/learn/amp-actions-and-events):
+The `amp-date-countdown` component exposes the following event that you can use
+[AMP on-syntax to trigger](https://amp.dev/documentation/guides-and-tutorials/learn/amp-actions-and-events):
 
 | Event     | Description                                                                                                                                                                                                                                                                                                             |
 | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -221,4 +241,6 @@ Renders as:
 
 ## Validation
 
-See [amp-date-countdown rules](https://github.com/ampproject/amphtml/blob/master/extensions/amp-date-countdown/validator-amp-date-countdown.protoascii) in the AMP validator specification.
+See
+[amp-date-countdown rules](https://github.com/ampproject/amphtml/blob/master/extensions/amp-date-countdown/validator-amp-date-countdown.protoascii)
+in the AMP validator specification.
diff --git a/extensions/amp-date-display/amp-date-display.md b/extensions/amp-date-display/amp-date-display.md
index 3b58d3b91567..48284b3dbbfe 100644
--- a/extensions/amp-date-display/amp-date-display.md
+++ b/extensions/amp-date-display/amp-date-display.md
@@ -50,7 +50,13 @@ limitations under the License.
 
 ## Behavior
 
-The `amp-date-display` component displays time data that you can render in your AMP page. By providing specific [attributes](#attributes) in the `amp-date-display` tag, the `amp-date-display` extension returns a list of time parameters, which you can pass to [an amp-mustache template](https://amp.dev/documentation/components/amp-mustache) for rendering. Refer to the [list below for each returned time parameter](#returned-time-parameters).
+The `amp-date-display` component displays time data that you can render in your
+AMP page. By providing specific [attributes](#attributes) in the
+`amp-date-display` tag, the `amp-date-display` extension returns a list of time
+parameters, which you can pass to
+[an amp-mustache template](https://amp.dev/documentation/components/amp-mustache)
+for rendering. Refer to the
+[list below for each returned time parameter](#returned-time-parameters).
 
 ### Example
 
@@ -100,32 +106,43 @@ This table lists the format you can specify in your Mustache template:
 
 ## Attributes
 
-You must specify at least one of these required attributes: `datetime`, `timestamp-ms`, or `timestamp-seconds`.
+You must specify at least one of these required attributes: `datetime`,
+`timestamp-ms`, or `timestamp-seconds`.
 
 ##### datetime
 
-The `datetime` attribute specifies the date and time in a standard ISO 8601 date string (e.g. 2017-08-02T15:05:05.000Z) or the string `now`. If set to `now`, `amp-date-display` will use the time the page loaded to render its template.
+The `datetime` attribute specifies the date and time in a standard ISO 8601 date
+string (e.g. 2017-08-02T15:05:05.000Z) or the string `now`. If set to `now`,
+`amp-date-display` will use the time the page loaded to render its template.
 
 ##### timestamp-ms
 
-The `timestamp-ms` attribute specifies the date and time using the number of milliseconds since 1970-01-01T0:00:00.000Z
+The `timestamp-ms` attribute specifies the date and time using the number of
+milliseconds since 1970-01-01T0:00:00.000Z
 
 ##### timestamp-seconds
 
-The `timestamp-seconds` attribute specifies the date and time using the number of seconds since 1970-01-01T0:00:00.000Z
+The `timestamp-seconds` attribute specifies the date and time using the number
+of seconds since 1970-01-01T0:00:00.000Z
 
 ##### locale (optional)
 
-An internationalization language string for each timer unit. The default value is `en` (for English). This attribute supports all values that are supported by the user's browser.
+An internationalization language string for each timer unit. The default value
+is `en` (for English). This attribute supports all values that are supported by
+the user's browser.
 
 ##### display-in (optional)
 
-If set to the value `utc`, the `display-in` attribute will convert the given date to UTC.
+If set to the value `utc`, the `display-in` attribute will convert the given
+date to UTC.
 
 ##### offset-seconds (optional)
 
-The `offset-seconds` attribute specifies an integer number of seconds to shift the given date.
+The `offset-seconds` attribute specifies an integer number of seconds to shift
+the given date.
 
 ## Validation
 
-See [amp-date-display rules](https://github.com/ampproject/amphtml/blob/master/extensions/amp-date-display/validator-amp-date-display.protoascii) in the AMP validator specification.
+See
+[amp-date-display rules](https://github.com/ampproject/amphtml/blob/master/extensions/amp-date-display/validator-amp-date-display.protoascii)
+in the AMP validator specification.
diff --git a/extensions/amp-date-picker/amp-date-picker.md b/extensions/amp-date-picker/amp-date-picker.md
index 557534d1bb82..abac75915c14 100644
--- a/extensions/amp-date-picker/amp-date-picker.md
+++ b/extensions/amp-date-picker/amp-date-picker.md
@@ -50,11 +50,13 @@ limitations under the License.
 
 ## Behavior
 
-You can use the `amp-date-picker` to render a calendar on a page that a user can select dates from.
+You can use the `amp-date-picker` to render a calendar on a page that a user can
+select dates from.
 
 _Example: Basic calendar_
 
-In this example, we display a fixed-height static calendar, where a user can select a single date:
+In this example, we display a fixed-height static calendar, where a user can
+select a single date:
 
 ```html
  
@@ -68,7 +70,8 @@ In this example, we display a fixed-height static calendar, where a user can sel
 
 _Example: Calendar for a specific input field_
 
-In this example, the calendar displays as an overlay for the specific form field:
+In this example, the calendar displays as an overlay for the specific form
+field:
 
 ```html
 
@@ -85,19 +88,31 @@ In this example, the calendar displays as an overlay for the specific form field
 
 ## Display modes
 
-The `amp-date-picker` provides two modes to render the date picker: static (default) or overlay.
+The `amp-date-picker` provides two modes to render the date picker: static
+(default) or overlay.
 
 ### Static mode
 
-By specifying `mode="static"`, the `amp-date-picker` renders a static calendar view. This is the default display mode; if no mode is specified, a static calendar is rendered.
+By specifying `mode="static"`, the `amp-date-picker` renders a static calendar
+view. This is the default display mode; if no mode is specified, a static
+calendar is rendered.
 
-For a static date picker, you must specify a size-defined layout, which can be one of: `fixed`, `fixed-height`, `responsive`, `fill` or `flex-item`.
+For a static date picker, you must specify a size-defined layout, which can be
+one of: `fixed`, `fixed-height`, `responsive`, `fill` or `flex-item`.
 
-When the `static` amp-date-picker is rendered in a ``, if there are no [inputs specified with `*input-selector`](#input-selector), the amp-date-picker creates hidden input elements (e.g., ``.
+When the `static` amp-date-picker is rendered in a ``, if there are no
+[inputs specified with `*input-selector`](#input-selector), the amp-date-picker
+creates hidden input elements (e.g., ``.
 
 _Example: static date picker in a form field_
 
-This example demonstrates using a static date picker in a form, where the user can select a date range in the calendar. As there are no `*input-selector` attributes defined in the amp-date-picker, hidden input fields are automatically generated.
+This example demonstrates using a static date picker in a form, where the user
+can select a date range in the calendar. As there are no `*input-selector`
+attributes defined in the amp-date-picker, hidden input fields are automatically
+generated.
 
 ```html
 
@@ -130,13 +145,19 @@ This example demonstrates using a static date picker in a form, where the user c
 
 ### Overlay mode
 
-By specifying `mode="overlay"`, when the user clicks, focuses, or presses the down-arrow in an input field connected with the amp-date-picker, the calendar appears. The calendar overlay positions itself relative to the `` tag.
+By specifying `mode="overlay"`, when the user clicks, focuses, or presses the
+down-arrow in an input field connected with the amp-date-picker, the calendar
+appears. The calendar overlay positions itself relative to the
+`` tag.
 
-For an overlay date picker, you must specify `layout="container"` and contain the input fields that it will render.
+For an overlay date picker, you must specify `layout="container"` and contain
+the input fields that it will render.
 
 _Example: overlay date picker in a form_
 
-This example demonstrates using a overlay date picker in a form where the user can choose a date. The date picker is connected to a specific input field via the `input-selector` attribute.
+This example demonstrates using a overlay date picker in a form where the user
+can choose a date. The date picker is connected to a specific input field via
+the `input-selector` attribute.
 
 ```html
 
@@ -159,10 +180,9 @@ This example demonstrates using a overlay date picker in a form where the user c
 ```
 
 On touch devices, an `amp-date-picker` in overlay mode automatically adds the
-`readonly` attribute to its `` elements.
-This prevents the device's on-screen keyboard from opening unncessesarily.
-To opt-out of this behavior, add the `touch-keyboard-editable` attribute to the
-`` element.
+`readonly` attribute to its `` elements. This prevents the device's
+on-screen keyboard from opening unncessesarily. To opt-out of this behavior, add
+the `touch-keyboard-editable` attribute to the `` element.
 
 
 
@@ -175,8 +195,8 @@ The `amp-date-picker` provides two types of dates to select:
 
 ### `type="single"`
 
-By specifying `type="single"`, the date picker attaches to a single input,
-and the user can select a single date. This is the default selection type.
+By specifying `type="single"`, the date picker attaches to a single input, and
+the user can select a single date. This is the default selection type.
 
 ```html
 
@@ -191,8 +211,8 @@ and the user can select a single date. This is the default selection type.
 
 ### `type="range"`
 
-By specifying `type="range"`, the date picker attaches to two inputs,
-and the user can select a date range with a starting date and ending date.
+By specifying `type="range"`, the date picker attaches to two inputs, and the
+user can select a date range with a starting date and ending date.
 
 ```html
 
@@ -210,8 +230,8 @@ and the user can select a date range with a starting date and ending date.
 `amp-date-picker` attributes accept dates in ISO 8601.
 
 [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) formats dates as `YYYY-MM-DD`
-and is the standard for sharing dates between electronic systems.
-For example, ISO 8601 formats the date February 28 2018 as `2018-02-28`.
+and is the standard for sharing dates between electronic systems. For example,
+ISO 8601 formats the date February 28 2018 as `2018-02-28`.
 
 ## Attributes
 
@@ -219,9 +239,10 @@ For example, ISO 8601 formats the date February 28 2018 as `2018-02-28`.
 
 Specifies how the date picker is rendered. Allowed values are:
 
-- **`static`** (default): The date picker renders as an interactive calendar view.
-- **`overlay`**: The date picker calendar view is not rendered until the user interacts
-  with required input field(s) nested in the ``.
+- **`static`** (default): The date picker renders as an interactive calendar
+  view.
+- **`overlay`**: The date picker calendar view is not rendered until the user
+  interacts with required input field(s) nested in the ``.
 
 ##### type
 
@@ -232,16 +253,16 @@ Specifies the selection type for the date picker. Allowed values are:
 
 ##### input-selector
 
-A query selector for a single date picker's input. If this is omitted,
-the date picker automatically generates a hidden input field, and assigns it
-a name of `date` or `${id}-date` using the date picker's id. If either of these conflict
+A query selector for a single date picker's input. If this is omitted, the date
+picker automatically generates a hidden input field, and assigns it a name of
+`date` or `${id}-date` using the date picker's id. If either of these conflict
 with an existing element in the form, an error is emitted.
 
 When `amp-date-picker` loads, the input element's value is used to display the
 initially selected date.
 
-Specify the `date` property via the [`src` attribute](#src) to set
-an initial date dynamically.
+Specify the `date` property via the [`src` attribute](#src) to set an initial
+date dynamically.
 
 ```html
 
@@ -308,32 +329,37 @@ an initial end date dynamically.
 
 ##### min
 
-The earliest date that the user may select. This must be formatted as an ISO 8601 date.
-If no `min` attribute is present, the current date will be the minimum date.
+The earliest date that the user may select. This must be formatted as an ISO
+8601 date. If no `min` attribute is present, the current date will be the
+minimum date.
 
-The `min` attribute may be updated after a user gesture with [`amp-bind`](https://amp.dev/documentation/components/amp-bind).
+The `min` attribute may be updated after a user gesture with
+[`amp-bind`](https://amp.dev/documentation/components/amp-bind).
 
 ##### max
 
-The latest date that the user may select. This must be formatted as an ISO 8601 date.
-If no `max` attribute is present, the date picker will have no maximum date.
+The latest date that the user may select. This must be formatted as an ISO 8601
+date. If no `max` attribute is present, the date picker will have no maximum
+date.
 
-The `max` attribute may be updated after a user gesture with [`amp-bind`](https://amp.dev/documentation/components/amp-bind).
+The `max` attribute may be updated after a user gesture with
+[`amp-bind`](https://amp.dev/documentation/components/amp-bind).
 
 ##### month-format
 
-The format to use for displaying the month in the calendar view.
-The default format is: `"MMMM YYYY"`.
+The format to use for displaying the month in the calendar view. The default
+format is: `"MMMM YYYY"`.
 
 ##### format
 
-The format to use for displaying and parsing the date in the input boxes.
-The default format is `"YYYY-MM-DD"`.
+The format to use for displaying and parsing the date in the input boxes. The
+default format is `"YYYY-MM-DD"`.
 
 ##### week-day-format
 
-The format to use for displaying the day of the week in the calendar view.
-If no `week-day-format` is present, the weekdays display as the first character of the weekday.
+The format to use for displaying the day of the week in the calendar view. If no
+`week-day-format` is present, the weekdays display as the first character of the
+weekday.
 
 ```html
 
 
 
-The `src` attribute may be updated after a user gesture with [`amp-bind`](https://amp.dev/documentation/components/amp-bind).
+The `src` attribute may be updated after a user gesture with
+[`amp-bind`](https://amp.dev/documentation/components/amp-bind).
 
 ###### template definition objects
 
-The `dates` property is an array of ISO 8601 single dates.
-The `id` property specifies the `id` of a template that the date picker can use to
-render the specified dates in the calendar view.
+The `dates` property is an array of ISO 8601 single dates. The `id` property
+specifies the `id` of a template that the date picker can use to render the
+specified dates in the calendar view.
 
 ```json
 {
@@ -465,9 +500,9 @@ render the specified dates in the calendar view.
 }
 ```
 
-If no `dates` property is specified in a template definition object, the template
-with the given `id` will be used as the default template to render any dates
-that do not have an explicitly specified template.
+If no `dates` property is specified in a template definition object, the
+template with the given `id` will be used as the default template to render any
+dates that do not have an explicitly specified template.
 
 ```json
 {"id": "my-default-template-id"}
@@ -523,8 +558,8 @@ _Example: Markup using the `src` attribute_
 
 ##### fullscreen
 
-Renders the picker to fill the space available to it, like in a fullscreen lightbox.
-This works best with `layout="fill"`.
+Renders the picker to fill the space available to it, like in a fullscreen
+lightbox. This works best with `layout="fill"`.
 
 ```html
 
@@ -554,43 +589,49 @@ This works best with `layout="fill"`.
 
 ##### open-after-select
 
-If present, keeps the date picker overlay open after the user selects a date or dates. By default, this attribute is not present.
+If present, keeps the date picker overlay open after the user selects a date or
+dates. By default, this attribute is not present.
 
 ##### open-after-clear
 
-If present, keeps the date picker open after the user clears the date or dates. By default, this attribute is not present.
+If present, keeps the date picker open after the user clears the date or dates.
+By default, this attribute is not present.
 
 ##### hide-keyboard-shortcuts-panel
 
-If present, hides the keyboard shortcuts panel at the bottom of the picker. By default, this attribute is not present.
+If present, hides the keyboard shortcuts panel at the bottom of the picker. By
+default, this attribute is not present.
 
 ##### common attributes
 
-This element includes [common attributes](https://amp.dev/documentation/guides-and-tutorials/learn/common_attributes) extended to AMP components.
+This element includes
+[common attributes](https://amp.dev/documentation/guides-and-tutorials/learn/common_attributes)
+extended to AMP components.
 
 ## Events
 
-These events may trigger actions on other AMP components using the `on` attribute.
-e.g. `on="activate: my-lightbox.open"`
+These events may trigger actions on other AMP components using the `on`
+attribute. e.g. `on="activate: my-lightbox.open"`
 
-Read more about [AMP Actions and Events](https://amp.dev/documentation/guides-and-tutorials/learn/amp-actions-and-events).
+Read more about
+[AMP Actions and Events](https://amp.dev/documentation/guides-and-tutorials/learn/amp-actions-and-events).
 
 ##### activate
 
-The date picker triggers the `activate` event when the user begins
-an interaction with the calendar view, i.e. when the overlay would open.
+The date picker triggers the `activate` event when the user begins an
+interaction with the calendar view, i.e. when the overlay would open.
 
 ##### deactivate
 
-The date picker triggers the `deactivate` event when the user ends
-their interaction with the calendar view, i.e. when the overlay would close.
+The date picker triggers the `deactivate` event when the user ends their
+interaction with the calendar view, i.e. when the overlay would close.
 
 ##### select
 
-The date picker triggers the `select` event when the user selects a date or
-date range. When selecting a date range, the event is emitted when the end
-date and start date are both selected.
-The `select` event contains the following properties.
+The date picker triggers the `select` event when the user selects a date or date
+range. When selecting a date range, the event is emitted when the end date and
+start date are both selected. The `select` event contains the following
+properties.
 
 For a single date picker:
 
@@ -655,7 +696,8 @@ For a date range picker:
 These actions may be triggered by other components using the `on` attribute.
 e.g. `on="tap: date-picker.setDate(date=state.value)"`
 
-Read more about [AMP Actions and Events](https://www.ampproject.org/docs/interaction_dynamic/amp-actions-and-events).
+Read more about
+[AMP Actions and Events](https://www.ampproject.org/docs/interaction_dynamic/amp-actions-and-events).
 
 ##### clear
 
@@ -668,8 +710,8 @@ or date range picker with the specified `id`, e.g. `date-picker`.
 
 ##### setDate
 
-The `setDate` action assigns the value of the `date` argument to
-the single date picker with the specified `id`, e.g. `date-picker`.
+The `setDate` action assigns the value of the `date` argument to the single date
+picker with the specified `id`, e.g. `date-picker`.
 
 ```html
 
@@ -702,9 +744,9 @@ e.g. `date-picker`. The `offset` argument value can be any integer.
 
 ##### startToday
 
-The `startToday` action assigns the value of the current day,
-plus an `offset` argument, to the date range picker with the specified `id`,
-e.g. `date-picker`. The `offset` argument value can be any integer.
+The `startToday` action assigns the value of the current day, plus an `offset`
+argument, to the date range picker with the specified `id`, e.g. `date-picker`.
+The `offset` argument value can be any integer.
 
 ```html
 
@@ -712,8 +754,8 @@ e.g. `date-picker`. The `offset` argument value can be any integer.
 
 ```
 
-The `startToday` action can be combined with the `endToday` action
-to select ranges with an offset.
+The `startToday` action can be combined with the `endToday` action to select
+ranges with an offset.
 
 ```html
 
@@ -735,8 +777,8 @@ e.g. `date-picker`. The `offset` argument value can be any integer.
 
 ```
 
-The `endToday` action can be combined with the `startToday` action
-to select ranges with an offset.
+The `endToday` action can be combined with the `startToday` action to select
+ranges with an offset.
 
 ```html