Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 42 additions & 42 deletions ads/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,26 +13,26 @@ This guide provides details for ad networks to create an `amp-ad` integration fo

<!-- {"maxdepth": 2} -->

- [Overview](#overview)
- [Constraints](#constraints)
- [The iframe sandbox](#the-iframe-sandbox)
- [Available information to the ad](#available-information-to-the-ad)
- [Available APIs](#available-apis)
- [Exceptions to available APIs and information](#exceptions-to-available-apis-and-information)
- [Ad viewability](#ad-viewability)
- [Ad resizing](#ad-resizing)
- [Support for multi-size ad requests](#support-for-multi-size-ad-requests)
- [amp-consent integration](#amp-consent-integration)
- [Optimizing ad performance](#optimizing-ad-performance)
- [Ad markup](#ad-markup)
- [1st party cookies](#1st-party-cookies)
- [Developer guidelines for a pull request](#developer-guidelines-for-a-pull-request)
- [Files to change](#files-to-change)
- [Verify your examples](#verify-your-examples)
- [Tests](#tests)
- [Lint and type-check](#lint-and-type-check)
- [Other tips](#other-tips)
- [Developer announcements for ads related API changes](#developer-announcements-for-ads-related-api-changes)
- [Overview](#overview)
- [Constraints](#constraints)
- [The iframe sandbox](#the-iframe-sandbox)
- [Available information to the ad](#available-information-to-the-ad)
- [Available APIs](#available-apis)
- [Exceptions to available APIs and information](#exceptions-to-available-apis-and-information)
- [Ad viewability](#ad-viewability)
- [Ad resizing](#ad-resizing)
- [Support for multi-size ad requests](#support-for-multi-size-ad-requests)
- [amp-consent integration](#amp-consent-integration)
- [Optimizing ad performance](#optimizing-ad-performance)
- [Ad markup](#ad-markup)
- [1st party cookies](#1st-party-cookies)
- [Developer guidelines for a pull request](#developer-guidelines-for-a-pull-request)
- [Files to change](#files-to-change)
- [Verify your examples](#verify-your-examples)
- [Tests](#tests)
- [Lint and type-check](#lint-and-type-check)
- [Other tips](#other-tips)
- [Developer announcements for ads related API changes](#developer-announcements-for-ads-related-api-changes)

## Overview

Expand All @@ -44,15 +44,15 @@ If you are an ad technology provider looking to integrate with AMP HTML, please

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.
- 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.

## The iframe sandbox

Expand Down Expand Up @@ -199,9 +199,9 @@ window.context

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 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.

#### Specifying an overflow element

Expand Down Expand Up @@ -343,12 +343,12 @@ Please read through [developing.md](../docs/developing.md) before contributing t

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/_config.js`: Add service specific configuration here.
- `/3p/vendors/yournetwork.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.
- `/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/vendors/yournetwork.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.

### Verify your examples

Expand Down Expand Up @@ -379,10 +379,10 @@ To speed up the review process, please run `amp lint` and `amp check-types`, the

### Other tips

- Add **cc ampproject/wg-monetization** 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](../docs/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:
- Add **cc ampproject/wg-monetization** 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](../docs/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.

Expand Down
59 changes: 29 additions & 30 deletions ads/google/a4a/docs/Network-Impl-Guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@ This guide outlines the requirements and steps for ad networks to implement Fast
Fetch for early ad request and support for AMP ads returned by the ad network to
be given preferential rendering.

- _Status: Draft_
- _Authors: [[email protected]](mailto:[email protected]),
[[email protected]](mailto:[email protected])_
- _Last Updated: 1-27-2016_
- _Status: Draft_
- _Authors: [[email protected]](mailto:[email protected]),
[[email protected]](mailto:[email protected])_
- _Last Updated: 1-27-2016_

<!--
(Do not remove or edit this comment.)
Expand All @@ -16,19 +16,19 @@ be given preferential rendering.
amp markdown-toc --fix
-->

- [Background](#background)
- [Overview](#overview)
- [Detailed design](#detailed-design)
- [Ad server requirements](#ad-server-requirements)
- [SSL](#ssl)
- [AMPHTML ad creative signature](#amphtml-ad-creative-signature)
- [Ad response headers](#ad-response-headers)
- [Creating an AMPHTML ad extension implementation](#creating-an-amphtml-ad-extension-implementation)
- [Create the implementation script](#create-the-implementation-script)
- [Create the configuration file](#create-the-configuration-file)
- [Create documentation](#create-documentation)
- [Create tests](#create-tests)
- [Checklist for ad network implementation](#checklist-for-ad-network-implementation)
- [Background](#background)
- [Overview](#overview)
- [Detailed design](#detailed-design)
- [Ad server requirements](#ad-server-requirements)
- [SSL](#ssl)
- [AMPHTML ad creative signature](#amphtml-ad-creative-signature)
- [Ad response headers](#ad-response-headers)
- [Creating an AMPHTML ad extension implementation](#creating-an-amphtml-ad-extension-implementation)
- [Create the implementation script](#create-the-implementation-script)
- [Create the configuration file](#create-the-configuration-file)
- [Create documentation](#create-documentation)
- [Create tests](#create-tests)
- [Checklist for ad network implementation](#checklist-for-ad-network-implementation)

## Background

Expand Down Expand Up @@ -208,8 +208,7 @@ _For reference, see [Figure 1: Part A](#figure-1-fast-fetch-rendering-flow)_.
});
```

Example configs: [AdSense](https://github.com/ampproject/amphtml/blob/main/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/main/ads/_a4a-config.js).
Example usage of Google Ad Manager and AdSense configs can be seen in [\_a4a-config.js](https://github.com/ampproject/amphtml/blob/main/ads/_a4a-config.js).

#### Create documentation

Expand All @@ -226,14 +225,14 @@ for your AMP ad network implementation.

## Checklist for ad network implementation

- [ ] All Server-AMP communication done with SSL
- [ ] AMP ads sent to validation server
- [ ] Validated AMP ads sent from network to AMP with signature
- [ ] Validated AMP ads sent from network to AMP with appropriate headers
- [ ] File hierarchy created within amphtml/extensions
- [ ] Custom `amp-ad-network-<TYPE>-impl.js` overwrites `getAdUrl()`
- [ ] `<TYPE>-a4a-config.js` implements `<TYPE>IsA4AEnabled()`
- [ ] Mapping added for ad network to a4aRegistry map within `_a4a-config.js`
- [ ] Documentation written in `amp-ad-network-<TYPE>-impl-internal.md`
- [ ] Tests written in `test-amp-ad-network-<TYPE>-impl.js`
- [ ] Pull request merged to the repo
- [ ] All Server-AMP communication done with SSL
- [ ] AMP ads sent to validation server
- [ ] Validated AMP ads sent from network to AMP with signature
- [ ] Validated AMP ads sent from network to AMP with appropriate headers
- [ ] File hierarchy created within amphtml/extensions
- [ ] Custom `amp-ad-network-<TYPE>-impl.js` overwrites `getAdUrl()`
- [ ] `<TYPE>-a4a-config.js` implements `<TYPE>IsA4AEnabled()`
- [ ] Mapping added for ad network to a4aRegistry map within `_a4a-config.js`
- [ ] Documentation written in `amp-ad-network-<TYPE>-impl-internal.md`
- [ ] Tests written in `test-amp-ad-network-<TYPE>-impl.js`
- [ ] Pull request merged to the repo
4 changes: 2 additions & 2 deletions build-system/server/new-server/transforms/utilities/lazy.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
export class Lazy<T> {
private declare initializer_: () => T;
private declare value_: T | undefined;
declare private initializer_: () => T;
declare private value_: T | undefined;

constructor(initializer: () => T) {
this.initializer_ = initializer;
Expand Down
4 changes: 4 additions & 0 deletions build-system/tasks/check-links.js
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,10 @@ function checkLinksInFile(file) {
},
},
],
// Ignore:
// - 403 [Forbidden], some sites block automated requests.
// - 429 [Too Many Requests], some sites rate-limit requests.
aliveStatusCodes: [200, 403, 429],
};

return new Promise((resolve, reject) => {
Expand Down
30 changes: 15 additions & 15 deletions build-system/tasks/e2e/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,22 +10,22 @@ AMP contributors embrace testing to maintain confidence that their code is execu

<!-- {"maxdepth": 1} -->

- [What is an end-to-end test?](#what-is-an-end-to-end-test)
- [Choosing which features to test](#choosing-which-features-to-test)
- [Writing E2E tests](#writing-e2e-tests)
- [Debugging E2E tests](#debugging-e2e-tests)
- [What is an end-to-end test?](#what-is-an-end-to-end-test)
- [Choosing which features to test](#choosing-which-features-to-test)
- [Writing E2E tests](#writing-e2e-tests)
- [Debugging E2E tests](#debugging-e2e-tests)

This document is a usage guide. For full test command documentation, consult the following resource:

- [Information on executing tests](../../../docs/testing.md)
- [Information on executing tests](../../../docs/testing.md)

## What is an end-to-end test?

Let's compare the test types available to AMP contributors:

- Unit tests
- Integration tests
- End-to-end tests
- Unit tests
- Integration tests
- End-to-end tests

Unit tests are useful for testing individual behaviors of a feature or fix. They are cheap to execute since they use mocks heavily to eliminate dependencies that need to also be executed during testing. These should be the most common type of test for a feature. These should fail rarely for reasons other than bugs.

Expand All @@ -43,13 +43,13 @@ End-to-end tests are able to test a full page as the user's browser would load i

End-to-end tests should verify the most important user flows of a component. Prioritize tests for behaviors that would make the page appear very obviously broken if there was a failure. For example:

- The component's initial render
- Primary user interactions
- e.g. clicking the next button on a carousel
- Features with heavy usage by a large number of AMP publishers
- e.g. loading more content at the bottom of an amp page
- Important behaviors that are frequently broken
- e.g. browser updates often break video autoplay behavior
- The component's initial render
- Primary user interactions
- e.g. clicking the next button on a carousel
- Features with heavy usage by a large number of AMP publishers
- e.g. loading more content at the bottom of an amp page
- Important behaviors that are frequently broken
- e.g. browser updates often break video autoplay behavior

## Writing E2E tests

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
amp markdown-toc --fix
-->

- [section](#section)
- [section](#section)

This paragraph should be preserved.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ This TOC header has newlines and indentation that doesn't match the lookup strin
amp markdown-toc --fix
-->

- [section](#section)
- [section](#section)

## section

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@
amp markdown-toc --fix
-->

- [tacos](#tacos)
- [asada](#asada)
- [al pastor](#al-pastor)
- [veggie](#veggie)
- [tacos](#tacos)
- [asada](#asada)
- [al pastor](#al-pastor)
- [veggie](#veggie)

## tacos

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ This file has unparsable TOC options, but should still have a TOC and should not

<!-- unparsable -->

- [section](#section)
- [section](#section)

## section

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@

<!-- {"maxdepth": 1} -->

- [included header one](#included-header-one)
- [included header two](#included-header-two)
- [included header one](#included-header-one)
- [included header two](#included-header-two)

## included header one

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
amp markdown-toc --fix
-->

- [What's this?](#whats-this)
- [What's this?](#whats-this)

## What's this?

Expand Down
Loading
Loading