Notifications & Deep Links

Overview

VPort notifications are delivered two ways at once:

In your inbox — the bell icon in the app keeps a persistent list of everything you have received.
As a push — a banner on your device (Apple Vision Pro, iPhone, or Meta Quest) that appears even when the app is closed.

Most notifications are actionable: tapping one takes you straight to the screen it is about — the video that finished processing, the live stream that just started, or your wallet after a top-up. The instruction that tells the app where to go is called a deep link.

This page explains the deep link format VPort uses, lists the deep link produced by every notification type, and shows the full push payload so client and integration developers can parse it.

The `vcloud://` scheme

Every VPort deep link is a URI beginning with vcloud://. The path after the scheme names the destination and, where relevant, the specific entity:

vcloud://<area>/<id>

For example, vcloud://videos/6f9d2c1e-8a4b-4f77-9c2e-1b0a5d3e7f42 opens the video with that UUID. Global areas such as the wallet have no trailing id (vcloud://wallet/credits).

The deep link is always paired with a structured navigation envelope (see Push payload). Native clients should prefer the structured destination / destination_id fields and treat the raw vcloud:// URI as the canonical fallback.

Deep link examples by notification type

Every automatic VPort notification and the deep link it carries:

Notification	When it fires	Type (`category`)	Deep link example
A creator you follow is live	Someone you follow starts a live stream	`event_live`	`vcloud://live/6f9d2c1e-8a4b-4f77-9c2e-1b0a5d3e7f42`
Your live stream started	Your own broadcast goes live	`event_live`	`vcloud://live/2b7c9a0d-3e51-4c88-b6a2-9f4e1d0c5a83`
New content is ready	Your uploaded video finishes processing	`new_content`	`vcloud://videos/8d1f6b24-7c90-4a3e-8b15-0e2a9c7d4f61`
Payment successful	Credits are added after a purchase	`payment_success`	`vcloud://wallet/credits`
Low credit balance	Your balance drops to $2.00 or below	`credit_low`	`vcloud://wallet/credits`
Report received	We confirm a report you submitted	`system_alert`	`vcloud://support`

The live/<id>, videos/<id>, and wallet/credits paths are entity- or area-backed and land on a specific screen. vcloud://support intentionally points at the support landing page rather than a per-report view, so the tap always resolves to a real screen.

Push payload

Deep links travel inside the push payload's data envelope. VPort delivers all pushes through Firebase Cloud Messaging (FCM), which reaches Apple devices via APNs on the provider side. The envelope is schema-versioned so clients can select a parser.

Envelope keys

Key	Example	Notes
`schema_version`	`"1"`	Envelope version. Branch your parser on this.
`action`	`"OPEN_DESTINATION"`	The only action emitted today. Present only when a destination exists.
`destination`	`"live_event"`	Stable, client-independent target — see the table below.
`destination_id`	`"6f9d2c1e-…"`	Entity UUID. Omitted for global destinations such as `wallet`.
`deep_link`	`"vcloud://live/6f9d2c1e-…"`	Canonical fallback URI.
`category`	`"event_live"`	Notification type; maps to the APNs category / FCM click action.
`notification_uuid`	`"a1b2c3d4-…"`	Inbox row id (absent for inbox-skipping admin test pushes).
`notification_type`	`"event_live"`	Same value as `category`.
`source_entity_type`	`"event_footage"`	The entity that triggered the notification.
`source_entity_uuid`	`"6f9d2c1e-…"`	UUID of that entity.

destination is one of a fixed set of values. Native and web clients map each onto their own routes:

`destination`	Meaning	Carries `destination_id`?
`creator_video`	A creator's processed video	Yes
`broadcast_status`	The owner's view of their own live stream	Yes
`live_event`	A live stream to watch	Yes
`wallet`	The wallet / credits screen	No
`submitted_reports`	A report the user submitted	Yes

FCM example (Android / Quest and the transport for Apple)

The "a creator you follow is live" notification:

{
  "notification": {
    "title": "Ada is live",
    "body": "Tap to watch the live stream now."
  },
  "data": {
    "schema_version": "1",
    "action": "OPEN_DESTINATION",
    "destination": "live_event",
    "destination_id": "6f9d2c1e-8a4b-4f77-9c2e-1b0a5d3e7f42",
    "deep_link": "vcloud://live/6f9d2c1e-8a4b-4f77-9c2e-1b0a5d3e7f42",
    "category": "event_live",
    "notification_type": "event_live",
    "notification_uuid": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "source_entity_type": "event_footage",
    "source_entity_uuid": "6f9d2c1e-8a4b-4f77-9c2e-1b0a5d3e7f42",
    "event_footage_uuid": "6f9d2c1e-8a4b-4f77-9c2e-1b0a5d3e7f42"
  }
}

APNs example (Apple Vision Pro / iPhone)

The same notification as it reaches an Apple device — the envelope keys ride alongside the standard aps dictionary as top-level custom fields:

{
  "aps": {
    "alert": { "title": "Ada is live", "body": "Tap to watch the live stream now." },
    "sound": "default",
    "category": "event_live"
  },
  "schema_version": "1",
  "action": "OPEN_DESTINATION",
  "destination": "live_event",
  "destination_id": "6f9d2c1e-8a4b-4f77-9c2e-1b0a5d3e7f42",
  "deep_link": "vcloud://live/6f9d2c1e-8a4b-4f77-9c2e-1b0a5d3e7f42",
  "category": "event_live",
  "notification_type": "event_live",
  "source_entity_uuid": "6f9d2c1e-8a4b-4f77-9c2e-1b0a5d3e7f42"
}

A "payment successful" push carries no destination_id because the wallet is a global screen:

{
  "data": {
    "schema_version": "1",
    "action": "OPEN_DESTINATION",
    "destination": "wallet",
    "deep_link": "vcloud://wallet/credits",
    "category": "payment_success",
    "notification_type": "payment_success"
  }
}

Parsing guidance for clients

Read schema_version first and select the matching parser.
If action is OPEN_DESTINATION, route on destination and, when present, destination_id.
If the client does not recognize a destination, fall back to opening the raw deep_link URI.
The deep_link, destination, action, category, and schema_version keys are transport-owned: the server assigns them last, so custom-data keys can never overwrite or redirect a notification.
Notifications with an empty destination (some admin test pushes) are intentionally non-navigable — show them in the inbox but do not attempt to open a screen.

Overview​

The vcloud:// scheme​

Deep link examples by notification type​

Push payload​

Envelope keys​

FCM example (Android / Quest and the transport for Apple)​

APNs example (Apple Vision Pro / iPhone)​

Parsing guidance for clients​