Skip to content

Copy edit #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dgash wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Copy edit #23

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

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 27 additions & 72 deletions extensions/amp-user-notification/amp-user-notification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,35 +14,18 @@ See the License for the specific language governing permissions and
limitations under the License.
-->

### <a name="amp-user-notification"></a> `amp-user-notification`
## <a name="amp-user-notification"></a> `amp-user-notification`

Displays a dismissable notification to the user. By supplying two URLs that
get called before the notification is shown and after it is dismissed,
it is possible to control per user as to whether the notification should
be shown (using the `ampUserId` value).
E.g. it could only be shown to users in certain geo locations or
prevent showing it again to the user when they've dismissed it before.
Displays a dismissable notification to the user.

---
### Usage
By supplying two URLs &mdash; one called before the notification is shown and one called after it is dismissed &mdash; it is possible to control per user (using the `ampUserId` value) whether the notification should be shown. For example, a notification might only be shown to users in certain geolocations, or you might prevent showing it again to a user who has dismissed it before.

#### Usage
The two URLs are provided by the `data-show-if-href` and `data-dismiss-href` attributes. An `id` is required, as multiple `amp-user-notification` elements are allowed and the `id` is used to differentiate them.

`amp-user-notification` requires 2 URLs which can be provided by
the `data-show-if-href` and `data-dismiss-href` attributes. An `id` is required
as multiple `amp-user-notification` elements are allowed and the
id is used to differentiate them.
To close `amp-user-notification`, add an `on` attribute to a button with the following value scheme: `on="event:idOfUserNotificationElement.dismiss"` (see example below). This user action also triggers the `GET` to the `data-dismiss-href` URL. Be mindful of the browser caching the `GET` response; see details below. We recommend adding a unique value to the `GET` URL, such as a timestamp, as a query string field.

To close `amp-user-notification` add a `on` attribute to a button with the
following value scheme `on="event:idOfUserNotificationElement.dismiss"`
(see example below). This user action also triggers the `GET` to the
`data-dismiss-href` URL. Be very mindful of the browser caching the `GET` response
and see details below in the `data-show-if-href` section. (We recommend
adding a unique value to the `GET` url like a timestamp as a query string field)

When multiple `amp-user-notification` elements are on a page, only one is shown
at a single time (Once one is dismissed the next one is shown).
The order of the notifications being shown is currently not deterministic. (TODO:
follow up task #1229 to fix this).
When multiple `amp-user-notification` elements are on a page, only one is shown at a time; when one is dismissed the next one is shown. The order in which notifications are shown is currently not deterministic. (TODO: follow up task #1229 to fix this).

Example:

Expand All @@ -58,21 +41,13 @@ Example:
</amp-user-notification>
```

---

#### Attributes
### Attributes

**data-show-if-href** (Required)

AMP will make a [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS)
GET request to this URL to determine whether the notification should be shown.
We will append the `elementId` and `ampUserId` query string fields to the href provided
on the `data-show-if-href` attribute. (see #1228 on why this is a GET instead of a POST)
AMP will make a [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) GET request to this URL to determine whether the notification should be shown. It will append the `elementId` and `ampUserId` query string fields to the href provided on the `data-show-if-href` attribute. (See #1228 on why this is a GET instead of a POST.)

For best practice to not let the browser cache the GET response values you should add
a [`TIMESTAMP` url replacement](https://github.com/ampproject/amphtml/blob/master/spec/amp-var-substitutions.md) value to the `data-show-if-href` attribute value.
You can add it as a query string field. (ex.
`data-show-if-href="https://foo.com/api/show-api?timestamp=TIMESTAMP"`)
To prevent the browser from caching the GET response values, you should add a [TIMESTAMP URL replacement](https://github.com/ampproject/amphtml/blob/master/spec/amp-var-substitutions.md) value to the `data-show-if-href` attribute value. You can easily add it as a query string field, e.g., `data-show-if-href="https://foo.com/api/show-api?timestamp=TIMESTAMP"`.

- `CORS GET request` query string fields
- `elementId`
Expand All @@ -84,9 +59,7 @@ You can add it as a query string field. (ex.
```

- `CORS GET response` json fields
The response must contain a single JSON object with a field
"showNotification" of type boolean. If this field is `true` the
notification will be shown, otherwise it will not be shown.
The response must contain a single JSON object with a field "showNotification" of type boolean. If this field is `true` the notification will be shown; otherwise it will not be shown.

- `showNotification`

Expand All @@ -97,13 +70,9 @@ You can add it as a query string field. (ex.

**data-dismiss-href** (Required)

AMP will make a [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS)
POST request to this URL transmitting the `elementId` and
`ampUserId` only when the user has explicitly agreed.
AMP will make a [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) POST request to this URL transmitting the `elementId` and `ampUserId` only when the user has explicitly agreed.

Use the `ampUserId` field to store that the user has seen the notification before
if you want to avoid showing it in the future. (It is the same value that
will be passed in future requests to data-show-if-href)
Use the `ampUserId` field to indicate whether the user has seen the notification before if you want to avoid showing it in the future. It is the same value that will be passed in future requests to `data-show-if-href`.

- `POST request` json fields

Expand All @@ -116,35 +85,21 @@ will be passed in future requests to data-show-if-href)
```
- `POST response` should be a 200 HTTP code and no data is expected back.

---

#### JSON Fields

- `elementId` (string) - The HTML id used on `amp-user-notification` element.
- `ampUserId` (string) - This id is passed to both this request and the dismiss request.
The id will be the same for this user going forward, but no other requests
in AMP send the same id.
You can use the id on your side to lookup/store whether the user has
dismissed the notification before.
- `showNotification` (boolean) - Boolean value wether the notification should be shown.
If `false` the promise associated to the element is resolved right away.
### JSON Fields

---
- `elementId` (string): The HTML ID used on the `amp-user-notification` element.
- `ampUserId` (string): This ID is passed to both this request and the dismiss request. The ID will be the same for this user going forward, but no other requests in AMP will send the same ID. You can use the ID on your side to lookup/store whether the user has dismissed the notification before.
- `showNotification` (boolean): Boolean value indicating whether the notification should be shown. If `false` the promise associated with the element is resolved right away.

#### Styling
### Styling

The `amp-user-notification` component should always have `layout=nodisplay`
and will be `position: fixed` after layout (default is bottom: 0, which can be overridden).
If a page has more than 1 `amp-user-notification` element then the notifications
are queued up and only shown when the previous notification has been dismissed.
The `amp-user-notification` component should always have `layout=nodisplay` and will be set to `position: fixed` after layout (default is `bottom: 0`, which can be overridden). If a page has more than one `amp-user-notification` element then the notifications are queued and only shown when the previous notification has been dismissed.

The `amp-active` (visibility: visible) class is added when the notification is displayed and
and removed when the notification has been dismissed.
`amp-hidden` (visibility: hidden) is added when the notification has been dismissed.
The `amp-active` (visibility: visible) class is added when the notification is displayed and removed when the notification has been dismissed. The `amp-hidden` (visibility: hidden) class is added when the notification has been dismissed.

You can for example hook into these classes for a "fade in" transition.
You can, for example, hook into these classes for a "fade in" transition.

ex. (w/o vendor prefixes)
Example (without vendor prefixes):

```css
@keyframes fadeIn {
Expand All @@ -158,10 +113,10 @@ ex. (w/o vendor prefixes)
}
```

#### Delaying Client ID generation until the notification is acknowledged
### Delaying Client ID generation until the notification is acknowledged

Optionally one can delay generation of Client IDs used for analytics and similar purposes until an `amp-user-notification` is confirmed by the user. See these docs for how to implement this:
Optionally you can delay generation of Client IDs used for analytics and similar purposes until an `amp-user-notification` is confirmed by the user. See these docs for how to implement this:

- [CLIENT_ID URL substitution.](../../spec/amp-var-substitutions.md#CLIENT_ID)
- [`amp-ad`](../../builtins/amp-ad.md)
- [`amp-analytics`](../amp-analytics/amp-analytics.md)
- [CLIENT_ID URL substitution.](../../spec/amp-var-substitutions.md#CLIENT_ID)
- [`amp-ad`](../../builtins/amp-ad.md)
- [`amp-analytics`](../amp-analytics/amp-analytics.md)