Skip to main content

World Kindness Day Lens Setup

Set up the SPECS Lens of the World Kindness Day sample: its scene and scripts, its Snap Cloud connection, and testing in Preview and on SPECS.

  • Snapchat: not supported
  • SPECS: fully supported
  • Camera Kit Web: not supported
  • Camera Kit Mobile: not supported
  • SnapchatNot supported
  • SPECSFully supported
  • Camera Kit WebNot supported
  • Camera Kit MobileNot supported

Platform details

  • Snapchat — Not supported.

  • SPECS — Fully supported.

  • Camera Kit Web — Not supported.

  • Camera Kit Mobile — Not supported.

The World Kindness Day sample project shows how a SPECS experience sends structured data to a database, and how the same data appears both in the Lens and in an external web app. The Lens invites users to choose a balloon and speak a kindness pledge. When they do, the Lens writes a record to the database and the global pledge counter updates.

You can find the project in the SPECS sample projects on the Lens Studio Home Page, and its source in the Snap Cloud World Kindness Day folder of the specs-devs/samples repository on GitHub.

The project is built for SPECS: set the Preview device to SPECS 27. It also needs your own Snap Cloud project: without a backend, the Lens doesn't work. Follow World Kindness Day Snap Cloud Setup before continuing.

Before you start

  • Lens Studio 5.25 or later. You can download the latest version of Lens Studio from ar.snap.com.
  • A SPECS device and the SPECS App, both up to date, to test on the device.

World Kindness Day project overview

Scene objects

  • Start Screen Root: the balloon selection screen.
    • Description Frame: holds the title and description texts.
    • Pledge Frame: holds the pledge texts.
    • Several interactable balloons.
  • End Screen Root: the thank-you message and the global pledge count.
    • Thank-You Frame: holds the title text, the thank-you text, and the global pledge count text.
    • Balloons Container: the parent for balloons instantiated in the "sky."
  • MainManager:
    • All script components are on this parent scene object.
    • ReminderHint: a reminder to set up a Snap Cloud project before using the sample.

Scripts

  • KindnessCounter.ts: the Snap Cloud integration, the pledge logic, the totals, and the UI state.
  • BalloonManager.ts: the balloon interactions; it triggers the pledge.
  • PledgeReadInOrder.ts: the voice trigger that detects the spoken pledge phrase.
  • SnapCloudRequirements.ts: holds the SupabaseProject asset that KindnessCounter reads its project from.

Assets

  • The Interaction Kit and UI Kit packages.
  • The SupabaseClient package.
  • The SnapDecorators and Utilities packages.
  • The SupabaseProject credentials asset, imported from the Supabase panel.
  • Prefabs: three balloon variants.
  • Materials, textures, scripts, fonts, and more.

Set up the Snap Cloud project for the Lens

You need a Snap Cloud project with the same tables and RPC functions this Lens uses. Follow World Kindness Day Snap Cloud Setup, which walks you through:

  • Creating your Snap Cloud project.
  • Adding the required tables (kindness_pledges, kindness_totals).
  • Creating the RPC functions (pledge_and_total_once, get_kindness_total_all, and more).
  • Setting the right permissions.
  • Optionally, adding test data to verify your setup.

Finish the backend setup before running the Lens: until then, it can't read or write any data.

Connect the World Kindness Day Lens to Snap Cloud

  1. Install the Supabase Client package, log in with your Snapchat account, and create or choose a project: see Get Started.
  2. In the Supabase panel, select Import Credentials on your project. It creates a SupabaseProject asset in the Asset Browser.
  3. Drag the asset into the Supabase Project input of the SnapCloudRequirements component. KindnessCounter reads the project from the component in its Snap Cloud Requirements input.

The project already has its objects and scripts set up. Check that these KindnessCounter inputs are assigned, or the Lens reports missing inputs:

  • Snap Cloud Requirements: the SnapCloudRequirements component that holds your project.
  • Balloon Prefabs: the balloon prefab array is filled.
  • Start Root and End Root: assigned to the right scene object groups.
  • Total Text: linked to its Text component in the scene.

How the World Kindness Day Lens works

From the Lens to Snap Cloud:

  1. The user selects a balloon.
  2. The user speaks: "I promise to be kind today."
  3. The Lens calls pledge_and_total_once().
  4. Snap Cloud inserts the user's record once, a trigger increments the total once, and the function returns the new global total.

From Snap Cloud to the Lens:

  1. The Lens receives the updated total.
  2. It shows the end screen.
  3. It spawns balloon prefabs, up to the configured maximum.

From the web app to Snap Cloud:

  1. The web app requests get_kindness_total_all().
  2. It updates the page when the total changes.

To set up the web app, see World Kindness Day Web App Setup.

Key scripts in the World Kindness Day Lens

KindnessCounter.ts

Handles every interaction with Snap Cloud. It signs the user in, checks whether they have already pledged, calls the pledge_and_total_once RPC, retrieves the global total, and updates the Lens UI. It also decides whether the user sees the start screen or the end screen, and instantiates balloon prefabs based on the number of global pledges.

BalloonManager.ts

Handles the balloon interaction logic. Each balloon has an Interactable component that detects pinches. When a user selects a balloon, the script starts the pledge flow by calling PledgeReadInOrder.init(). When the pledge is done, its changeTransform function plays the balloon's lift animation and calls KindnessCounter.onBalloonSelected().

PledgeReadInOrder.ts

Coordinates the voice interaction. After the user selects a balloon, it turns on the on-device ASR Module and listens for the pledge phrase ("I promise to be kind today"). Once it detects the phrase, it calls BalloonManager.changeTransform to finish the pledge and submit it to Snap Cloud.

Test the World Kindness Day Lens

Test in Lens Studio Preview

  1. Open the Preview panel.
  2. Set the Preview device to SPECS 27: see Preview Lenses for SPECS.
  3. Check that the SupabaseProject credentials are imported and assigned on the SnapCloudRequirements component.
  4. In the Preview panel, test the balloon interactions, the spoken pledge phrase, and the change from the start screen to the end screen.

Test on SPECS

  1. Send the Lens to SPECS: see Send a Lens to SPECS.
  2. Pinch a balloon to begin.
  3. Speak your pledge ("I promise to be kind today"). Your balloon floats up.

The Lens sends your pledge to Snap Cloud and shows the updated global total on the end screen.