Custom Sound Feature

Play your own uploaded sounds on demand from JavaScript, pair them with haptic feedback, and reuse them for push notifications across Android and iOS.

Lets your app play a custom sound — uploaded once via the WebToNative Dashboard — instead of relying only on the device's default sound. This page covers the shared prerequisite (uploading the file) and how the feature fits together; each way of actually playing the sound has its own dedicated page:

Page	What it covers
Sound.play	Play the uploaded sound immediately, triggered directly from your JavaScript.
Haptics.trigger	Play the uploaded sound alongside a haptic vibration effect, in one call.
Notification Sound	Have a remote push notification play the uploaded sound automatically when it arrives (via OneSignal or FCM).

You'll need to import the javascript file in your website before starting from this link.

Platform support: Android and iOS.

---

How It Works

One uploaded sound file can be used in all three places above, and all three reference it by the same name:

1. Sound.play(soundName) — plays it immediately from JavaScript (e.g. a chat "message sent" ping, a game effect). See Sound.play.

2. Haptics.trigger({ effect, soundName }) — plays it alongside a haptic vibration effect, in one call. See Haptic Feedback.

3. A remote push notification — OneSignal or FCM tells the OS to play it automatically when a push arrives. See Notification Sound.

The sound file itself is never sent from your JavaScript or from a push payload — only its name is. It must already be uploaded to your app via the Dashboard (below) before you reference it from any of the three places above.

---

Uploading the Sound File (Dashboard)

Go to your WebToNative Dashboard → Add-ons → Notification → OS Notification Sound and upload the sound file under the platform's sound setting. Android and iOS each have their own separate upload field — uploading for one platform does not make the file available on the other, so upload the same audio to both fields if you want consistent behavior across platforms.

• Reference name: the name you pass to Sound.play / soundName is derived from the uploaded file's name, minus its extension.

• Format: only .mp3 and .wav files can be uploaded — these are the only supported formats on both platforms.

• Extension: .mp3 is the default — if you call Sound.play("your_sound_name") without an extension, .mp3 is assumed automatically, so you don't need to pass anything if you uploaded an .mp3 file. If you uploaded a .wav file, you must pass the extension explicitly — Sound.play("your_sound_name.wav") — or the lookup will assume .mp3 and fail to find it.

Changes take effect on your app's next build — if you're testing on a device already running an older build, rebuild/reinstall after uploading a new or changed sound file.

---

Frequently Asked Questions

Do I need to enable an add-on on the WebToNative Dashboard to use this?

Yes — you need to add the OS Notification Sound add-on from WebToNative. Once it's added, you can upload your sound file under OS Notification Sound, in the Notification section of Add-ons, for each platform you want it on. The JavaScript bridge works as soon as it's imported as usual.

Can I use the same sound file for `Sound.play`, `Haptics.trigger`, and a push notification?

Yes — upload it once per platform via the Dashboard, and reference it by the same name from all three. For the push notification side, the platform-specific dashboard/API fields have their own naming conventions (extension required on iOS, omitted on Android) — see Notification Sound.

What audio formats are supported?

Only .mp3 and .wav — these are the only formats you can upload, on either platform. .mp3 is assumed by default if you don't pass an extension in Sound.play; for .wav, pass the extension explicitly.

Why did I get `PERMANENTLY_BLOCKED` or no sound after asking for notification permission?

That's unrelated to this page — Sound.play/Haptics.trigger play immediately from JavaScript and don't require notification permission at all. Notification permission only affects whether the OS shows/plays a remote push automatically; see Permission for permission handling, and Notification Sound for push-specific sound setup.