Clarify behavior of substitutions with amp-analytics

[rudygalfi]

It appears that several substitutions are default-defined to be used in the amp-analytics variable syntax.

For instance, this ping to send a page view ID can be constructed in two ways: ?pvid=PAGE_VIEW_ID or ?pvid=${pageViewId} since the variable pageViewId inherits the value of PAGE_VIEW_ID by default.

The documentation should clarify how variables can be introduced and used in amp-analytics and talk about any default values inherited from the more general substitution scheme.

cc @avimehta

[Meggin]

Drafted two docs on variables in this PR (including a doc specifically on variable precedence): ampproject/amp.dev#46

[Meggin]

Analytics docs have landed. Variable substitution is covered throughout the docs, as well as specifically described in here: https://www.ampproject.org/docs/guides/analytics/analytics_basics.html#variable-substitution and in here: https://www.ampproject.org/docs/guides/analytics/deep_dive_analytics.html#variable-substitution-ordering.

Do you need more, or can we close?

[rudygalfi]

I want something that makes it super-clear that VARIABLE_NAME as a substitution is the same thing as ${variableName} as an amp-analytics var.

Another way to talk about this is how https://github.com/ampproject/amphtml/blob/master/extensions/amp-analytics/analytics-vars.md is very redundant with https://github.com/ampproject/amphtml/blob/master/spec/amp-var-substitutions.md and there's nothing talking about how these relate to each other. It might be nice to have a single file that lists the value that's provided ("Screen height") and shows it both as a substitution ("SCREEN_HEIGHT") and as the variable available in amp-analytics ("screenHeight").

[avimehta]

Note that the two lists may be different. Look for requestCount. Over long term, I imagine they will diverge as amp-analytics adds support for vars that the platform may not understand. (No concrete examples yet but if we need to report on viewability of certain elements on page, we would do that calculation in amp-analytics and not in var-substitution).

[rudygalfi]

Agree. In that case, the platform (substitution) column will just say "N/A". I think by pulling these into the same file, we may the relationship more understandable and the documentation more maintainable.

[avimehta]

@Meggin Any progress on this? I will need this for an upcoming feature. If you haven't started and or can't, I'll be happy to take this over..

[rudygalfi]

@avimehta I suspect it will be best for you to take it from here. cc @bpaduch