Browse documentationApp analytics

App analytics

App sources keep usage, errors, releases, and reports together without requiring an account ID from the person using your software. Each installation uses a random local identifier.

Create an app source

An organization owner creates the source and its ingest key.

  1. Add an App source.Place it under the product it belongs to.
  2. Review collection.Choose usage, errors and reports, country, and device details.
  3. Create an ingest key.Save the full value when it appears. Vital shows it once.
  4. Open Live.Keep it nearby while you send the first event.

Choose a client

Vital currently provides its app integration during onboarding. Rust apps can use Vital's current Rust client, which has built-in consent gates, durable batching and retries, plus an optional panic-reporting hook. It is supplied to approved projects and is not published as a public crate.

Other platforms can use the HTTPS ingest API. The example below is useful for proving the connection. A production client should add a bounded queue, backoff, lifecycle flushing, and the consent controls appropriate for its platform.

Create an install ID

Generate one random UUID when the app first runs, save it in local app settings, and reuse it. Keep it stable across upgrades so one installation does not become a new user every release. Do not derive it from a name, email address, license key, machine serial, or account ID.

Install identity pattern
// Pseudocode: replace these functions with your platform's secure storage.
// Create the UUID once, save it locally, and reuse it after upgrades.
const installId = await loadInstallId() ?? crypto.randomUUID();
await saveInstallId(installId);

Send a first event

This request sends one fictional app_open event. Replace the key, platform, and version with values from your App source. Keep the event ID stable if this exact item is retried.

First app event
const eventId = crypto.randomUUID();

const response = await fetch("https://pulse-in.syvr.dev/v1/batch", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PK_LIVE_INGEST_KEY",
  },
  body: JSON.stringify({
    sdk: { name: "example-app", version: "1.0.0" },
    sentAt: new Date().toISOString(),
    install: installId,
    context: {
      platform: "windows",
      appVersion: "1.0.0",
      channel: "release",
    },
    items: [{
      type: "event",
      id: eventId,
      ts: new Date().toISOString(),
      name: "app_open",
    }],
  }),
});

if (response.status !== 202) {
  throw new Error("Vital returned " + response.status);
}

const result = await response.json();
console.log(result.accepted, result.rejected);

A successful request returns HTTP 202 with an accepted count and arejected list. Check both. One invalid item can be rejected while valid items in the same batch are accepted.

Handle delivery

  • Reuse an item's UUID whenever you retry it, so Vital can deduplicate the item.
  • Retry network failures, HTTP 408, HTTP 429, and server errors with backoff. Respect Retry-After.
  • Stop or correct the request after other client errors instead of retrying the same invalid batch forever.
  • Bound local storage and memory. Analytics should never prevent the app from starting or closing.
  • Queue only after the user has opted in when your product or region requires consent.
  • Flush at safe lifecycle points, while accepting that a final event can be lost during a hard exit.

Source collection settings determine what Vital accepts. Client consent determines what leaves the device. Use both layers rather than treating one as a replacement for the other.

Collect suggestions inside your app

Add a form with a title and details field, then send it to Vital when someone chooses to submit. They don't need Discord or a Vital account. Suggestions stay private to your organization and appear in Suggestions, separate from bug reports. You can filter by source and status, open the full idea, and mark it New, Triaged, Resolved, or Ignored.

The Rust helper accepts a title up to 120 UTF-16 units and details up to 4,500. Both are required. It sends the text with the install ID, platform, app version, and channel. It doesn't attach recent activity, logs, screenshots, a session, or contact details. Your app owns the form and decides when submission is allowed.

Rust suggestion helper
// Use pulse-rs 0.2.1 or newer after your normal setup and consent checks.
// Keep this ID for unchanged retries. Create a new one when the text changes.
let draft_id = pulse::Uuid::new_v4();
let result = pulse
    .suggestion("Add compact mode", "Show more files at once.")
    .id(draft_id)
    .send_now(std::time::Duration::from_secs(5));

A Sent result means Vital accepted it. Queued means it's saved locally for another attempt, so don't tell someone it has arrived yet. Keep their draft after an error. Reuse the same UUID for unchanged retries; create a new one if they edit the title or details. The Rust client is supplied during onboarding, not through a public crates.io package.

Other clients can use the existing reports endpoint with category: "idea", the title in description, and details in steps. Use your source's ingest key, never a server or admin key in a distributed app. Browser keys must allow the exact origin.

Suggestion over HTTPS
// Create draftId once per draft, outside your retry loop.
const draftId = crypto.randomUUID();
const form = new FormData();
form.append("report", JSON.stringify({
  id: draftId,
  category: "idea",
  description: "Add compact mode",
  steps: "Show more files at once.",
  install: installId,
  context: { platform: "windows", appVersion: "1.0.0", channel: "release" },
  sdk: { name: "example-app", version: "1.0.0" },
}));
const response = await fetch("https://pulse-in.syvr.dev/v1/reports", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_PK_LIVE_INGEST_KEY" },
  body: form,
});
// Let fetch set the multipart Content-Type and boundary.
if (response.status !== 202) throw new Error("Suggestion wasn't accepted");
const receipt = await response.json(); // { id: "..." }

Your tools can retrieve ideas with list_suggestions and get_suggestionthrough Vital's MCP connection or the authenticated REST API. set_suggestion_statusrequires write access. Suggestion reads contain the submitted text and source information, not nearby activity or crash diagnostics.

Collection and retention

Suggestions use the existing Errors and reports collection setting and report rate limits. They're kept for 180 days. Turning off that setting stops new suggestions too. No extra backend or key is required.

Verify the connection

Run the app once and open Live for its source. The event should appear with the platform, app version, and release channel you sent. Allow up to one minute after creating a key or changing a source policy.

Need the supported client for your stack?

Include your platform and framework when you request access. We will help you choose the current integration path.