Lens+
The subscription capability lets a Web Lens put content behind Lens+. Your game checks whether the player can use that content, and if they can't, asks Snapchat to show the Lens+ upgrade offer. Snapchat handles the payment, so your game never takes one.
Before you submit
Only a Lens+ Lens has Lens+ content, so a Lens whose code calls snapchat.subscription has to be one.
- A Lens that calls the API is served to Snapchat 14.33 or later. When you submit it, Snapchat records 14.33 as the oldest version that can run the Lens, so players on older versions don't get it.
- Submitting a new Lens that calls the API enrolls it in Lens+. The usual Lens+ requirements apply: a verified phone number, Lens+ program eligibility, Public visibility, a video as the first preview, monthly Lens+ quota left, and no music.
- An update can't add the calls to a Lens that isn't a Lens+ Lens. Decide before the first submission.
- Only calls count. Snapchat scans your code for calls on
snapchat.subscription, or on a variable that holds it. Including the API without callingsubscriptiondoesn't enroll the Lens, and neither does passing the namespace to a function and calling it there. Call the methods onsnapchat.subscriptiondirectly.
Publishing covers the rest of the upload and review.
Check support
Check snapchat.isSupported('subscription') after init(), and keep the game playable when it's false.
Gate content on eligible
const { eligible } = await snapchat.subscription.getStatus();
bonusLevel.locked = !eligible;
On a Lens+ Lens, a player with Lens+ is eligible, and anyone else isn't until they subscribe.
Offer the upgrade
requestUpgrade() shows the Lens+ upgrade offer, then Snapchat's own paywall if the player taps through. It resolves when the flow ends:
const { subscribed, reason } = await snapchat.subscription.requestUpgrade();
subscribedis whether the player has Lens+ now.reasonappears when the upgrade offer didn't complete for a reason other than the player's choice:
reason | Meaning |
|---|---|
too_soon | requestUpgrade() was called too soon after the Lens opened. Snapchat showed nothing, so wait a moment and try again. |
already_in_flight | Another upgrade offer is on screen. Snapchat showed nothing. |
user_ineligible | The player can't buy Lens+ in the app, for example because they manage their subscription elsewhere. Snapchat tells them so. |
requestUpgrade() rejects with ERR_INTERNAL when nothing can present the offer.
Unlock a bonus level
Act on the result of requestUpgrade() rather than waiting for a change event, because not every host sends one:
async function unlockBonusLevel() {
if (!snapchat.isSupported('subscription')) return false;
try {
if ((await snapchat.subscription.getStatus()).eligible) return true;
const { subscribed, reason } = await snapchat.subscription.requestUpgrade();
if (reason) console.info('Upgrade offer not completed:', reason);
return subscribed;
} catch (e) {
console.warn('Lens+ unavailable:', e.message);
return false;
}
}
To react when a subscription completes somewhere else, such as another Lens or Settings, listen for changes. onStatusChanged() returns a function that stops listening:
const stopListening = snapchat.subscription.onStatusChanged(({ eligible }) => {
bonusLevel.locked = !eligible;
});
When every player is eligible
On a Lens that isn't a Lens+ Lens, every player is eligible, and requestUpgrade() resolves { subscribed: true } without showing anything. Anything you gate is then open to everyone. That is the case:
- until the Lens is live as a Lens+ Lens, which happens some time after it passes review;
- when you push the Lens to your own device;
- if the Lens stops being a Lens+ Lens;
- if the submission scan found no calls, so the Lens was never enrolled.
Test on the desktop
The desktop stub serves subscription too, so you can build and test the locked path outside Snapchat. Its player starts without Lens+. requestUpgrade() subscribes them after a fake half-second upgrade offer and fires onStatusChanged once. The stub never declines or throttles, so the reason values only show up inside Snapchat.
SubscriptionAPI in the API reference lists every method and return value.