A4a format spec by tdrl · Pull Request #4263 · ampproject/amphtml

tdrl · 2016-07-29T00:18:00Z

This is a draft specification for the format of A4A ad documents (a.k.a., "A4A creatives").

…format-spec

kashyapnitin · 2016-07-29T12:35:30Z

extensions/amp-a4a/amp-a4a-format.md

+1. Media: Videos must not enable autoplay.
+
+  _Rationale_: Autoplay forces video content to be downloaded immediately, which
+ slows the page load.  Further, users dislike auto-playing video ads.


can we remove users dislike bit.. until we can link to any corresponding research?

michaelkleber · 2016-07-29T15:25:20Z

extensions/amp-a4a/amp-a4a-format.md

+## A4A Format Rules
+
+1. The creative must obey all rules given by the [AMP format rules](../.
+./spec/amp-html-format.md), included here by reference.  _*In addition*_:


This is technically not accurate, since we modify the usual rule set (e.g. change the boilerplate), not just add further restrictions to it.

Good catch! Added some exception wording to this section. PTAL.

RByers · 2016-07-30T05:34:37Z

extensions/amp-a4a/amp-a4a-format.md

+Note that the same rules about mutations to the boilerplate text apply as in 
+the [general AMP boilerplate](https://github.com/ampproject/amphtml/blob/master/spec/amp-boilerplate.md).
+
+### CSS


Perhaps touch-action should also be prohibited to ensure ads can't interfere with the ability to scroll the document?

Great point!

Added a restriction on touch-action. @RByers -- please check for correctness and make sure the rationale is right?

Sorry for the delay, just got back from vacation. LGTM

michaelkleber · 2016-08-05T16:58:32Z

Note @avimehta's open PR #4368 to let <amp-analytics> use "amp-ad" as a selector. Looks like the syntax will be:

"visibilitySpec": {
    "selector": "amp-ad",
    "visiblePercentageMin": 50,
    "continuousTimeMin": 1000
}

raymall · 2016-08-05T23:30:48Z

extensions/amp-a4a/amp-a4a-format.md

+}
+```
+
+**Bad**


-No vendor prefixed
Blacklist vendor-prefixes in the css completely. (-webkit-, -moz-, etc)

Sounds plausible to me, but, again, not enough CSS knowledge. Can you provide a rationale? And maybe some feedback from one of the CSS-knowledgeable AMP folks -- @dvoytenko ? Also @Gregable for feasibility of implementing the necessary validation checks? (I'd guess not too hard, but I don't want to assume with no knowledge.)

Yes, blacklist vendor prefixes. We can insert them as needed.

Oh shoot. I missed this one on my second pass. There was some other discussion of this in a separate email thread. I'll copy the key points here:

@powdercloud said:

The spec does not talk about vendor specific prefixes, e.g., -moz-transition or -webkit-

transition. I think there's more than one way to handle these. E.g.:

(1) Disallow any vendor prefixes for transition, animation, transform, visibility, opacity.
(2) Consider -moz-foo an alias for foo, that is, strip the vendor specific prefixes for the purpose of validation.
(3) Just ignore the issue.

Opinions?

My random thoughts:
(1) may be nice if these prefixes were only useful until every browser supported the non-prefixed stuff. And it may not be good to have stylesheets that differentiate between vendors since the CSS is already constrained to be simple/fast for the ads.
(2) is perhaps the most flexible, slightly more complicated than (1) - not much really.
(3) is bad because -webkit-transition may be a backdoor for when transition isn't allowed.

I think my default choice may be (2).

And then @cramforce said:

Yes, (2), please :)

It sounds like the folks working on validator code went with approach 2, and I think it meets the needs expressed here. So I'll add it to the doc.

Gregable · 2016-08-12T21:34:04Z

extensions/amp-a4a/amp-a4a-format.md

+  <tr><td>amp-kaltura-player</td></tr>
+  <tr><td>amp-lightbox</td></tr>
+  <tr><td>amp-list</td></tr>
+  <tr><td>amp-live-list</td></tr>


Does live-list make sense in an ad? Are the ads contents going to be updating over time?

Not sure. This list came from @lannka -- hopefully he can comment on whether this is a needed feature. In general, though, I'd rather ban things that are clearly problematic, rather than things that are only questionably useful. Who knows what some clever advertiser will come up with to do with these? So unless you think live-list causes problems, I'm inclined to leave it.

Feedback from @jasti : It's okay to drop live-list.

bobcassels · 2016-08-25T21:42:27Z

extensions/amp-a4a/amp-a4a-format.md

+
+   _*In addition*_:
+
+1. The creative must use `<html a4⚡>` or `<html a4amp>` as its enclosing tags.


amp4ads fits better with our external comms, so far. Maybe ⚡4ads, too? Or just⚡ads.

Oh ugh. One missed TLA expansion and suddenly we're baked into the wrong interpretation. Personally, I'd rather change the external comms going forward -- there will be another round when A4A goes live, I'm sure. And we've all tried to be consistent about usage in this doc and everywhere in GitHub. It would be a pain to change all of it now.

Maybe someone who handles external comms could comment? Hey @jasti -- do you know who the right people to loop in are? The issue is that A4A is intended to mean "AMP Ads for AMPHTML Pages". But in the initial round of external comms (starting with @cramforce 's blog post), it was expanded to "AMP for Ads". So now @bobcassels and @taymonbeal are suggesting that we should change the formatting rules in this spec to match the "AMP for Ads" interpretation. I'm reluctant to do so.

Missed this. Quite true that although our initial focus was AMP Ads for AMP documents, it's certainly a huge focus for the quarter, according to @michaelkleber @lannka and @cramforce (see a note above from him, too).

If it's not terribly uncomfortable, we should switch to calling it AMP for Ads now OR we can wait until we are done with the work to cleanly support AMP ads outside of AMP documents and then revise the docs. (which I think we are aiming for the end of the quarter). Your call.

Ok, you all win. :-) A4A == AMP for Ads. Changed this doc. We'll have to look out for other points to change as well.

Note to @Gregable : Validator will have to change to match new html spec.

keithwrightbos · 2016-08-31T13:26:29Z

PR #4773 adds the ability for the href of an anchor within the creative to expanded on click allowing for capture of click X/Y, in addition to other expansion macros. One concern is that when the creative has been injected within a shadow root, this would allow for leaking page level information to the creative (e.g. DOCUMENT_REFERRER, PAGE_LOAD_TIME, TOTAL_ENGAGED_TIME, etc). There are a couple of ways to handle this:

Have the validation service check for the existence of these macros on any anchor href attributes and if present either disallow the document entirely or rewrite the href such that they are removed.
Attempt to generate values for some or all of these as if the creative had been wrapped in an iframe (e.g. referrer = ad request, load time = delta from page navigation start to when shadow dom was inflated, etc).

I propose item 1 for now and we can move some macros over as the need arises. Should I include this as part of the PR or wait until it is completed and then add?

cramforce · 2016-08-31T15:19:57Z

extensions/amp-a4a/amp-a4a-format.md

+Feedback from the community is welcome.  Please comment here or on the [Intent
+to Implement](https://github.com/ampproject/amphtml/issues/4264)_.
+
+A4A (AMP Ads for AMPHTML Pages) is a mechanism for rendering fast,


I, uhm, prefer "AMP for Ads.". I think this spec has wider scope as it largely applies to non-AMP containers.

Fair enough. I guess this is a lost fight now. :-) Updated.

tdrl · 2016-09-07T18:00:51Z

@keithwrightbos Re: click handling and anchor expansion. As I think about it, I'm not sure this doc is the best place to describe that. Maybe it should be described in detail in the variable substitions documentation and only mentioned here, with a cross-link? My rationale is that people looking to implement variables in their hrefs will be looking there first.

A lot also depends on whether it's a full validation error to have a disallowed parameter, or it simply gets silently ignored (possibly b/c the validation service silently rewrites it away). My inclination is to go for silent ignore, instead of invalidate page.

…e unbounded resources) and one that only works at page level.

cramforce · 2016-09-07T19:40:20Z

extensions/amp-a4a/amp-a4a-format.md

+should not attempt to include them directly.
+
+<table>
+  <tr><td>amp-accordion</td></tr>


Lets trim to

+ <tr><td>amp-accordion</td></tr> + <tr><td>amp-analytics</td></tr> + <tr><td>amp-anim</td></tr> + <tr><td>amp-audio</td></tr> + <tr><td>amp-carousel</td></tr> + <tr><td>amp-fit-text</td></tr> + <tr><td>amp-font</td></tr> + <tr><td>amp-form</td></tr> + <tr><td>amp-img</td></tr> + <tr><td>amp-pixel</td></tr> + <tr><td>amp-social-share</td></tr> + <tr><td>amp-video</td></tr>

These are also cut for now until we properly support them:

+ <tr><td>amp-image-lightbox</td></tr> + <tr><td>amp-lightbox</td></tr>

Done. Again, @jasti to double-check from a product perspective, but I'm okay with this list.

Thanks, looks like a good start.

cramforce · 2016-09-07T21:13:19Z

LGTM from my side. Let me know when this should land.

tdrl · 2016-09-07T21:19:13Z

@cramforce I think this is pretty stable now. All outstanding comments are addressed, as far as I can see. As @keithwrightbos mentions, there are some further issues that we need to discuss around URL variable substitution, but we've not yet settled how that will be handled, so we'd prefer to get this draft published and then iterate on future revisions.

So I'm happy for you to go ahead and merge / publish this. Thanks!

Terran Lane added 6 commits July 26, 2016 14:54

Draft of A4A format spec.

b75807f

Work on A4A format spec.

cdb0530

Draft of A4A format standard.

1db94b8

Draft of A4A format spec.

80867ed

Work on A4A format spec.

d618e43

Draft of A4A format standard.

8c8891b

tdrl mentioned this pull request Jul 29, 2016

Intent to Implement: Format Specification and Validation Rules for A4A Ad Documents #4264

Closed

Draft of A4A format standard.

55e7e1d

tdrl added NEEDS REVIEW WG: monetization labels Jul 29, 2016

Merge branch 'a4a-format-spec' of github.com:google/amphtml into a4a-…

9a19e2a

…format-spec

kashyapnitin reviewed Jul 29, 2016
View reviewed changes

Updates from reviews.

e25fb43

michaelkleber reviewed Jul 29, 2016
View reviewed changes

Terran Lane added 3 commits July 29, 2016 13:55

Updates from reviews.

187465f

Updates in response to reviews.

ba913c0

Updates in response to reviews.

5cae97e

RByers reviewed Jul 30, 2016
View reviewed changes

raymall reviewed Aug 5, 2016
View reviewed changes

Terran Lane added 2 commits August 9, 2016 19:56

Updates in response to reviews.

388b13d

Updates in response to reviews.

9c39e4d

Gregable reviewed Aug 12, 2016
View reviewed changes

Terran Lane added 4 commits August 16, 2016 11:59

Updates in response to reviews.

cdbfea9

Added prominent "Draft" banner.

9371536

Add extensions that were missed through copy-paste errors.

cc3a6c2

Add builtins to extensions section.

72ef3ca

bobcassels reviewed Aug 25, 2016
View reviewed changes

Add rule for vendor-prefixed CSS properties.

761890c

cramforce reviewed Aug 31, 2016
View reviewed changes

Terran Lane added 2 commits September 7, 2016 14:17

Changed the expasion of A4A to "Amp for Ads".

62f65d5

Removed some extensions that create iframes (and, therefore, could us…

380a8ee

…e unbounded resources) and one that only works at page level.

cramforce reviewed Sep 7, 2016
View reviewed changes

Removed additional extensions.

20c518f

Updated html tag to match "AMP for ads"

8d83a3e

cramforce added LGTM and removed NEEDS REVIEW labels Sep 7, 2016

cramforce merged commit 52c342c into ampproject:master Sep 8, 2016

tdrl deleted the a4a-format-spec branch September 8, 2016 17:04

dreamofabear pushed a commit to dreamofabear/amphtml that referenced this pull request Sep 16, 2016

A4A (AMP for Ads) format spec (ampproject#4263)

2443553

mityaha pushed a commit to brightcove-archive/ooyala_amphtml that referenced this pull request Nov 30, 2016

A4A (AMP for Ads) format spec (ampproject#4263)

ade9806

+              }
+              ```
+              **Bad**


		_In addition_:

		1. The creative must use `<html a4⚡>` or `<html a4amp>` as its enclosing tags.

Conversation

tdrl commented Jul 29, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michaelkleber commented Aug 5, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bobcassels Aug 25, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

keithwrightbos commented Aug 31, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tdrl commented Sep 7, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cramforce commented Sep 7, 2016

Uh oh!

tdrl commented Sep 7, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

12 participants

tdrl commented Jul 29, 2016 •

edited

Loading

bobcassels Aug 25, 2016 •

edited

Loading