Flowcards activation on AMP

xavi.beumala · September 2, 2022, 12:35pm

Flowcards are AMP-compatible.
Follow this guide to start using them in your AMP pages!

1. AMP extensions

Include the AMP-script extension, AMP-iframe extension and AMP-bind extension to your pages:

2. CSS Rules

Append the flowcards CSS rules to your AMP custom styles.

.mrf-flowcards-position-fixed {
	position: fixed;
	z-index: 2147483647;
}
#mrf-flowcards-wrapper {
	top: 0;
	transform: translate3d(0, var(--transform, 100%), 0);
	transition: var(--transition);
}
amp-img.mrf-hero-element-contain img {
	object-fit: cover;
}

3. Meta tag

Add a meta tag inside the document head to include the Flowcards script’s hash.

<meta name="amp-script-src" content="${script-sha}">

What is the amp-script-src meta?
AMP requires a hash to identify scripts for security reasons. The hash in this documentation always corresponds to the latest flowcards update, that you can also copy from this URL:
https://flowcards.mrf.io/statics/experience-amp/latest/csp-hash.txt

4. Flowcards HTML code

Finally, place the flowcard’s HTML code before your page’s content, at the beginning of the body tag:

Be aware that in the attribute src of the <amp-state> element you need to replace the ACCOUNT-ID with the same account ID you have in Compass

<amp-script
	layout="fixed-height"
  	src="https://flowcards.mrf.io/statics/experience-amp/${script-sha}/card-transitioner.es2015.js"
	height="1px"
	style="opacity: 1;"
	media="screen and (max-width:800px)"	
>
	<amp-state id="flowcardsState" src="https://flowcards.mrf.io/json/active?page_technology=1&site_id= ${ACCOUNT-ID} &client_id=CLIENT_ID(compass_uid)&canonical_url=CANONICAL_URL&hostname=CANONICAL_HOSTNAME&location=CANONICAL_URL&referrer=EXTERNAL_REFERRER&page_view_id_64=PAGE_VIEW_ID_64&scroll_height=SCROLL_HEIGHT&geo=__INJECT_GEO__&cid=_ga:CLIENT_ID(AMP_ECID_GOOGLE,,_ga),comScore:CLIENT_ID(comScore),compass_uid:CLIENT_ID(compass_uid)&version=${script-sha}"></amp-state>
	<div id="mrf-flowcards-wrapper" class="mrf-flowcards-position-fixed">
		<div id="mrf-flowcards-content-wrapper">
			<amp-iframe
				layout="fill"
				frameborder="0"
				sandbox="allow-scripts allow-top-navigation-by-user-activation allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
				[src]="flowcardsState.iframeUrl || 'https://flowcards.mrf.io/statics/experience-amp/${script-sha}/flowcards-content.html'"
				src="https://flowcards.mrf.io/statics/experience-amp/${script-sha}/flowcards-content.html"
			>
				<div placeholder>
					<div class="mrf-flowcards-loader"></div>
				</div>
			</amp-iframe>
		</div>
	</div>
</amp-script>

The position of this snippet on your page impacts the Flowcard's loading speed: make sure it is at the very beginning of the body tag, before any other element.

The <amp-state> element links to your flowcards.json configuration. This configuration determines the card content: make sure you don’t forget to include it!
Notice that there are both an src and a [src] attribute. Include both so that the card’s URL is dynamic, but keep the fallback as a good practice.
Feel free to replace the content of <div class="mrf-flowcards-loader"></div> with a message in your site’s language!

`<amp-consent>` component

If you use <amp-consent> in your AMP pages to comply with GDPR or other user privacy regulations, we recommend you to use the attribute data-block-on-consent with the value _till_responded, so that the user’s consent is properly propagated inside the Flowcard.

You will need to add it do both <amp-script> and <amp-iframe> elements

The code will look something like

<amp-script data-block-on-consent="_till_responded">
	<!-- Same code here -->
	<amp-iframe data-block-on-consent="_till_responded">
		<!-- Same code here -->
	</amp-iframe>
</amp-script>

`<amp-next-page>` component

If you are using <amp-next-page> in your AMP pages, we recommend you to use the attribute next-page-hide, so that Flowcards are not loaded multiple times. This attribute should be added to <amp-script> element.

The code will look like this

<amp-script
	layout="fixed-height"
  	src="https://flowcards.mrf.io/statics/experience-amp/${script-sha}/card-transitioner.es2015.js"
	height="1px"
	style="opacity: 1;"
	media="only screen and (max-width:800px)"
	next-page-hide
>
<!-- Same code here -->
</amp-script>

Do not add next-page-hide attribute if you are not using <amp-next-page>. Otherwise your AMP page may become invalid.

Hide Flowcards using Intersection Observer in AMP

Intersection Observer triggers are not supported in AMP. However, it is possible to force the Flowcard to hide on an intersection with a certain element. For instance, we may need flowcards to hide whenever a footer module comes into screen, to ensure its visibility.

Add Amp-animation and Amp-position-observer to the head of the page.

<script async="" custom-element="amp-animation" src="https://cdn.ampproject.org/v0/amp-animation-0.1.js"></script>
<script async="" custom-element="amp-position-observer" src="https://cdn.ampproject.org/v0/amp-position-observer-0.1.js"></script>

Add the following script next to your body (i.e. next to amp-script):

<amp-animation id="mrfHideFlowcardsAnimation" layout="nodisplay">
    <script type="application/json">
    {
      "duration": "2s",
      "fill": "forwards",
      "animations": [
        {
          "selector": "#mrf-flowcards-wrapper",
          "keyframes": [
            {"transform": "translate3d(0, 200vh, 0)"}
          ]
        },
        {
          "selector": "#mrf-flowcards-foreground",
          "keyframes": [
            {"offset": 0.9, "transform": "scale(1)", "opacity": 0},
            {"offset": 1, "transform": "scale(0)", "opacity": 0}
          ]
        }
      ]
    }
  </script>
</amp-animation>
<amp-position-observer
    id="mrfHideFlowcardsPositionObserver"
    target="{observable-element-id}"
    intersection-ratios="0"
    on="enter:mrfHideFlowcardsAnimation.start"
    layout="nodisplay"
>
</amp-position-observer>

Where {observable-element-id} is the id of the element whose appearance on screen must force the flowcard to hide.

Instead of declaring an id for this element as the script's target, it is also possible to declare amp-animation-observer inside this element, without defining any target, as explained here.

How to update Flowcards version

The hash you give to the amp-script-src meta corresponds to the Flowcards AMP build you are using. From time to time, Marfeel will add features to Flowcards, and you will need to update this hash in your AMP pages in order to benefit from them.

To update the build of Flowcards in your AMP pages:

Obtain the lastest hash from here
Make sure that all the <meta>, <amp-script>, <amp-state> and <amp-iframe> sources have the right hash in their path:

<meta name="amp-script-src" content=" ${HASH} ">
<amp-script> src

https://flowcards.mrf.io/statics/experience-amp/ ${HASH} /card-transitioner.es2015.js

<amp-iframe> src

https://flowcards.mrf.io/statics/experience-amp/ ${HASH} /flowcards-content.html

<amp-state> src

https://flowcards.mrf.io/json/active?page_technology=1&site_id= ${ACCOUNT-ID} &client_id=CLIENT_ID(compass_uid)&canonical_url=CANONICAL_URL&hostname=CANONICAL_HOSTNAME&location=CANONICAL_URL&referrer=EXTERNAL_REFERRER&page_view_id_64=PAGE_VIEW_ID_64&scroll_height=SCROLL_HEIGHT&geo=__INJECT_GEO__&cid=_ga:CLIENT_ID(AMP_ECID_GOOGLE,,_ga),comScore:CLIENT_ID(comScore),compass_uid:CLIENT_ID(compass_uid)&version=${HASH}

Replace ${HASH} by the lastest hash in those 4 places whenever you update your flowcards AMP version.

Example

Flowcards Playground also has working examples of Flowcards in AMP, so you can see them in action. Just select AMP before clicking Simulate

For example, you can see the Homepage experience working in an AMP page here