Amphtml: I2I: amp-story: Viewer message for user entering/exiting a page attachment

[drtchops]

Summary

It would be valuable for the viewer to be aware of when a user enters or exits a story page attachment.

API

I would be adding two new message from the AMP Document to the Viewer:

• pageAttachmentEntered when the user opens the attachment drawer
• pageAttachmentExited when the user closes the attachment drawer

Both events would have no data associated with them and would not expect a response.

Motivation

I would like my viewer's swipe function to be different depending on whether the user is looking at a swipe up or not. There is currently no way to definitively know this.

Additional context

Are the names of these events good? Are they clear as to what they do? Alternatively, should we have one event with a data parameter that indicated open vs closed?

/cc @ampproject/wg-approvers
/cc @ampproject/wg-stories
/cc @gmajoulet

[gmajoulet]

Thanks for filing this!

We're getting many feature requests aiming at retrieving a specific story state:

• is a page attachment open?
• is the story audio muted?
• what is the current page ID?

I'd like us to consider a viewer messaging that would retrieve story states, accepting a predefined list of arguments, ie: attachmentState, embedState (know if a tweet is expanded), storyProgress, mutedState, etc.

Would this still work for you? From your viewer, on touchstart you could get the attachmentState and decide whether or not you want to start swiping to the next document.

[newmuis]

For the attachment, won't we need some way of telling the story not to handle the swipe?

[drtchops]

I think this would work for our use case, thanks! Do you have an idea of when this would be implemented by?

[gmajoulet]

Coming back to this, we're still planning on implementing the viewer messaging I described in my previous comment, but we'd like to know a bit more about what you're trying to build.

Could you describe your viewer swipe behavior, and why you want the swipe to be different when a page attachment is displayed?
My point is that existing viewers have the following behavior:

• On swipe, if the DOM element DOES NOT HAVE a horizontal overflow, swipe to the next story
• On swipe, if the DOM element DOES HAVE a horizontal overflow, scroll the DOM element and don't swipe to the next story

If you're building a native viewer, you should be able to use native events, swipe animations, and horizontal scroll overflow detection.
If you're building a web viewer, you should be able to use the touchstart, touchmove, touchend events and they should work as described above.

Is there any reason why you don't want to swipe to a next story when the page attachment is open?

[drtchops]

I'm building a web viewer, and in testing I noticed a couple things. First, the document seems to fire the touch events regardless of if the event is inside of a horizontal scroll container. I suppose since the documents are on the same domain as the viewer I could use document.elementFromPoint and check myself, but that doesn't sound like the intended behaviour?

Secondly, I'm interested in implementing a "swipe down to close" gesture, which obviously I'd not want to trigger when the user is swiping the attachment down.

I also feel that swiping to the next story while the attachment is open is an odd behaviour that doesn't seem like a natural thing a user would want to do, but that's just my gut feel and may not be true once we test it.

Previously I also had an issue where the attachment would break when swiping away and then back while it was open, but that issue seems to be fixed (yay!).

Thank you for all your help!

[gmajoulet]

I'm building a web viewer, and in testing I noticed a couple things. First, the document seems to fire the touch events regardless of if the event is inside of a horizontal scroll container.

Are you talking about the touchstart touchmove touchend sent by the viewer postMessage API as you add the #cap=swipe capability?
If yes, that'd a bug that we'd want to fix.

Secondly, I'm interested in implementing a "swipe down to close" gesture, which obviously I'd not want to trigger when the user is swiping the attachment down.

We're going to allow this through the postMessage viewer messaging API, cf https://github.com/ampproject/amphtml/issues/25697. What's your timeline for this feature?

I also feel that swiping to the next story while the attachment is open is an odd behaviour that doesn't seem like a natural thing a user would want to do, but that's just my gut feel and may not be true once we test it.

This is ultimately up to you and we will provide the correct API for you to build it, my point was mostly to convince you that using the postMessage viewer API for your web viewer, instead of setting up your own listeners, is going to make your life easier :)

[drtchops]

Are you talking about the touchstart touchmove touchend sent by the viewer postMessage API as you add the #cap=swipe capability?
If yes, that'd a bug that we'd want to fix.

Yes, those are the events I'm using.

We're going to allow this through the postMessage viewer messaging API, cf #25697. What's your timeline for this feature?

👍 I don't currently have a timeline for this, but it'll likely be a nice to have in the next couple months.

This is ultimately up to you and we will provide the correct API for you to build it, my point was mostly to convince you that using the postMessage viewer API for your web viewer, instead of setting up your own listeners, is going to make your life easier :)

I am currently using the postMessage viewer API, I'm just not currently aware of any way to check if the attachment is open or closed using it.

[gmajoulet]

We're implementing a new getDocumentState/setDocumentState viewer API, that will allow you to check if the attachment is open.
I just sent the first PR #26285 and I'll ping/close this ticket once it supports retrieving the page attachment open/closed state.

[gmajoulet]

We added some code to forward vertical touch events, so you can build a "swipe down to close" feature in your viewer if you want to (https://github.com/ampproject/amphtml/pull/26303).

We also implemented this getDocumentState/setDocumentState API, and added an option to retrieve the PAGE_ATTACHMENT_STATE, which will allow you to do exactly what you expect (https://github.com/ampproject/amphtml/pull/26343).

I'm not sure of the exact messaging syntax but you will be able to use the following parameters:

const message = {
  name: 'getDocumentState',
  data: {state: 'PAGE_ATTACHMENT_STATE'},
  rsvp: true,
};
const response = await sendMessage(message);
console.log(response); // {state: 'PAGE_ATTACHMENT_STATE', value: true|false}

Please allow for up to 2 weeks for these new features to be available in production :))

[drtchops]

Awesome, thank you so much for your help on this!