Video and Lottie Animations on Paywalls

The paywall editor has a Video element and a Lottie element for motion on your paywall: a product demo, a looping background, an animated icon or a celebration at the end of an onboarding step. You add them like any other element, and they play inside the paywall on the device.

For shorter effects, such as a button that shrinks when tapped or text that fades in, use tap behavior animations or Effects instead.

Requirements

• Video and Lottie elements need no SDK setup. They play inside the paywall.
• To bundle a video with your app instead of downloading it, you need local resources: iOS SDK 4.13.0 or later, Android SDK 2.7.7 or later, or Expo SDK 1.1.3 or later.

Add a video

1. In the paywall editor, click + in the sidebar or the Layout tab, then choose Video.
2. Select the video. In the component editor, under Video, do one of these:
   • Click the upload button and choose a video file.
   • Paste the video's URL into the field.
   • Click Pick from Assets to use a video from your Assets library.
3. Turn the playback options on or off. See Video options.
4. Publish the paywall.

The Video header shows the file size and the video's dimensions, so you can check how large it is before you publish.

What happens when you upload

When you upload a video from the video field, the editor converts it in your browser before uploading:

• It re-encodes the video as an H.264 MP4. Videos longer than 2560 pixels on their long edge are scaled down to 2560.
• It saves the first frame as the video's poster.
• It uploads the original file too. The paywall plays the converted MP4 first, and the original only if the MP4 can't play.

Keep the tab open while the upload runs. If your browser can't encode H.264, the editor uploads the original file as is, with no poster.

Even after conversion, a long video takes time to download. Keep videos short, around 3 to 10 seconds, and a few megabytes.

Video options

A new video element starts with Autoplay, Loop and Muted on and Controls off. Every time the paywall opens, the video starts again from the beginning. Videos play inline in the paywall, not full screen.

You can also insert a variable into the video URL with the variable picker, for example to show a different video per user.

Add a Lottie animation

1. In the paywall editor, click + in the sidebar or the Layout tab, then choose Lottie.
2. Select the element. In the component editor, under Animation, paste the animation's URL, or click the upload button and choose a Lottie .json file.
3. Set the options. See Lottie options.
4. Publish the paywall.

Lottie options

A new Lottie element plays as soon as the paywall opens and loops. Every time the paywall opens, it starts again from the beginning.

Play, pause or react to the end

Each Lottie element has two element variables, under its name in the Variables tab:

• Is Playing: true while the animation plays. Set it to false to pause the animation and true to play it.
• Playback Progress: how far the animation has played, from 0 to 100. Set it to jump to that point.

To play or pause the animation when someone taps a button, add a tap behavior to the button with Update Variable, choose the Lottie's Is Playing variable, and set the Operation to Toggle.

Know when a Lottie animation ends

With Loop off, when the animation reaches its end, Is Playing becomes false and Playback Progress becomes 100. Use either one in a dynamic value to change the paywall when the animation finishes. For example, to show a Continue button only after the animation ends, give the button a dynamic value that hides it until Playback Progress is 100.

With Loop on, the animation never ends, and Is Playing stays true.

A video shows a black or blank frame before it plays

Until the video's first frame loads, the element shows its poster. If the video has no poster, nothing fills that space yet. To fix it:

1. Select the video and check for a poster. Videos uploaded from the video field get one from their first frame. Videos added by URL or from Pick from Assets don't, so click + Add Poster and add an image of the first frame.
2. Give the video a fixed height under Size, or an aspect-ratio that matches the video under Custom CSS, so the element keeps its size while the video loads.
3. Make the video load sooner. Turn on Cache on Device for the paywall, or bundle the video with your app as a local resource.

A Lottie animation blocks taps on a close button

A Lottie element catches taps like any other element. If it sits on top of a close button, for example as a full-screen overlay, the button under it can't be tapped. Do one of these:

• Select the close button and, under Position, give it a higher Z Index than the Lottie element.
• Select the Lottie element and, under Custom CSS, add pointer-events with the value none. Taps then go through the animation to whatever is under it. Don't do this if the Lottie element has its own tap behavior, because it stops receiving taps.

Things to know

• A video always fills its element and is cropped to fit, like object-fit: cover. Size the element to the video's aspect ratio to avoid cropping.
• Videos you link by URL, rather than upload, aren't converted, and the editor warns that external URLs can slow the paywall down and add CDN costs.
• A video picked from Assets plays the file as it's stored in Assets, without the converted MP4 or a poster.
• The Lottie element plays Lottie JSON files. The player and the animation file load over the network when the paywall loads. Lottie animations can't use local resources.
• Large videos and animations are the most common reason a paywall opens slowly. See Paywall Preloading and Caching.
• For Superwall Framework paywalls, which are built in code, see Lottie in Assets.

Related

• Local Resources
• Paywall Preloading and Caching
• Assets
• Navigation component
• Styling elements