Using Banners in AR Quicklooks

The default expectation in the quicklook UX on both Android and iOS that users will be jumping into, and then back out of quicklooks, ending up on the same webpage they launched from.

This doesn't need to be the case, however. Both platforms support tappable banners that can take the user to a new URL - whether its a shopping cart, an external site, or on to launch another quicklook.

This opens up a lot of possibilities, from tapping a banner to move to an animated version of a product, to tapping to change a sofa's color, to 'chaining' banners with multiple stages that you move through one at a time, like the lifecycle of a butterfly.

The actual layout and details vary across iOS and Android, but the core concept - tapping a button to move to a new URL is universal.

iOS Banners

iOS offers three separate approaches to banners - using their generic layout with text and a call to action, or inserting fully custom HTML.

Using a banner in iOS quicklooks will disable the photo function, as the banner appears where the photo button would normally be.

All the parameters discussed below should be appended to the end of the .usdz URL, with a #. They can be chained with & as with regular URL parameters. Remember to URL encode special characters:

<a rel="ar" href="model.usdz#canonicalWebPageURL=https://example.com/model&callToAction="Buy%20Now">
    <img src="model-preview.jpg">
</a>

Generic Banner

The following parameters can be set:

callToAction

The blue button text on the right. Space is limited so its best not to use dynamic text here.

checkoutTitle

The bold text at the top of the banner.

checkoutSubtitle

The grey text below the title. If too long it will be truncated with ellipses. No matter what, the price and domain the model is hosted on are appended to the end of this text.

price

Added to the end of the checkoutSubtitle, with a comma.

<a href="https://example.com/biplane.usdz#applePayButtonType=buy&checkoutTitle=Biplane%20Toy&checkoutSubtitle=Rustic%20finish%20with%20rotating%20propeller&price=$15"></a>

As of iOS 13.6 all fields must be filled (and cannot be empty strings) which may impact your ability to use this layout.

Custom HTML

You can also use your own HTML file provided as a URL in order to render custom layouts. Note that interactions with the banner (links, javascript etc) will not work - only the content is displayed.

custom

The absolute URL to the HTML file. This must be served via HTTPS.

customHeight

The height of the banner. Can be small, medium, or large to set the banner height to 81, 121, or 161 pts respectively. Default is small.

Listening for taps

Taps on the callToAction button, or anywhere on custom HTML banners, will be sent via JS events to the containing anchor.

To listen for taps set an eventListener for a message event on the anchor, and check the data property of the event for the value _apple_ar_quicklook_button_tapped

const el = document.getElementById("ar-anchor");
el.addEventListener("message", function (event) { 
  if (event.data == "_apple_ar_quicklook_button_tapped") {
       doSomething();  
    }
 }, false);

Note this implies that all your JS will continue to function while the user is in AR, which can be significant for analytics and responding to returns from AR.

iOS Banners & the Variant JS SDK

All the above properties can be set when launching an iOS quicklook via the Variant SDK:

var data = {
   options: {...},
   productCode: PRODUCT_CODE
   ios:{
      callToAction: "Buy Now!",
      canonicalWebPageURL: "https://example.com",
      applePayButtonType: "plain",
      checkoutTitle:"Red Car",
      checkoutSubtitle:"Convertible with custom rims",
      price: "$25",
      tapCallback: myFunction
   }
};

Variant.launchQuicklook(data);

You can also provide a tap callback by passing in a function to tapCallback. See the SDK Documentation for more details.

Android Banners

Android's quicklook banners are much more visually restrictive than iOS. If you absolutely require full customisation, you might consider using WebXR to build an experience identical across both platforms.

link

The URL the user will be redirected to when tapping the visit button. Unfortuately as of 07/20 you cannot set the 'Visit' message and icon to anything else. We have tried to accomodate this in some cases by using the word 'visit' in our title copy. (e.g. 'visit our new chatbot for more details').

Links will open in a new webview, contained within the Scene Viewer app showing the AR. This can make tracking a users progress through your site difficult (e.g. if you only want to show an AR onboarding message on first visit). We recommend using url parameters on any links you use that specify the source is from a banner. For example ?from_ar_banner=true .

title

Title that will appear on the left in larger lettering. The domain of the URL will always be placed below the title.

Android Banners & the Variant JS SDK

Both parameters above (and others listed in our Android quicklook guide) are supported in the Variant SDK:

var data = {
   options: {...},
   productCode: GREEN_GOLD_EBIKE
   android:{
       title: "Your Next E-bike"
       link: "https://example.com/learnmore?ar_src=banner"
       browser_fallback_url: "https://example.com/learnmore?ar_src=incompatible"
       resizable: false
   }
};

Variant.launchQuicklook(data);