Skip to content
Scalpels home

Scalpels is officially launching on October 31, 2026. Special early adopter pricing is available now.

← All documentation

Documentation

Telltale

Instrumenting your app

Updated

Your NativePHP app reports to Telltale through the artisan-build/telltale-client package. Scalpels does not do this step for you: Telltale has no connect flow, so you add the package and its two values to your app yourself.

Install the client

In your NativePHP application:

composer require artisan-build/telltale-client

The service provider is auto-discovered. It starts capturing as soon as the app has a URL and an ingest value.

Set the build environment

Set both values in every mobile and desktop build environment:

TELLTALE_URL=https://telltale.example.com
TELLTALE_INGEST=tti_<one-time-value>
  • TELLTALE_URL is the stable public address of your Telltale deployment, whether that is its laravel.cloud address or your own domain. See Getting started for why it must not change after clients begin using it.
  • TELLTALE_INGEST is the one-time value Telltale showed when you created the app.

Keep the name TELLTALE_INGEST. Do not rename it to something ending in _KEY, _TOKEN or _SECRET. The ingest value is designed to ship inside the build: it is write-only, it can only register devices and send events for its one app, and it cannot read anything back.

How delivery works

Capture never sends an HTTP request inline. Each event is written to a local SQLite outbox (database/telltale.sqlite by default) and drained later:

  • Mobile: a queued job on the app's database queue connection drains the outbox while the app is able to run. Nothing uploads in the background.
  • Desktop: the queue drains it, and the client also schedules a telltale:drain task every minute.

On first delivery the device generates a random install UUID, registers it with Telltale at /api/register using the ingest value, and receives its own per-install bearer token. Batches of up to 100 events are then gzipped and posted to /api/ingest. If delivery fails the client backs off, starting at 15 seconds and capping at an hour.

The outbox is bounded. It keeps at most 10,000 rows and drops anything older than 30 days; the number of dropped events is reported to Telltale and shown as client-reported drops.

What is captured automatically

  • Screen views: NativePHP Mobile screen mounted, resumed and unmounted signals; desktop window focus and blur, and route changes.
  • Estimated sessions: a session starts with the first event and a new one starts after 30 minutes of inactivity.
  • Context, once per session: app version, platform, device model, OS and version, locale, and on mobile the network state.
  • PHP errors that Laravel reports, plus failed queued jobs on mobile.

Privacy and data has the full list and what is not captured.

Record your own events

Use the Telltale facade (ArtisanBuild\TelltaleClient\Facades\Telltale):

Telltale::event('checkout_completed', ['plan' => 'pro']);

Event names are what the funnel tool matches against, so keep them stable across releases. Property keys and values are length-capped.

Other calls you can make:

  • Telltale::identify($opaqueUserId) attaches an opaque user id. Use a one-way hash, not an email address or other direct personal data.
  • Telltale::beforeSend(fn (array $event) => ...) lets you scrub an event or return null to drop it.
  • Telltale::optOut() stops capture and clears the outbox; Telltale::optIn() resumes it.

Correlate with your backend

The client adds an X-Telltale-Session header to your app's own outbound Laravel HTTP requests:

X-Telltale-Session: v1;session=<raw-session-uuid>;install=<sha256-install-hash>

The install part is a SHA-256 hash, never the raw install id, ingest value or token. Requests to Telltale itself never get the header. For a plain Guzzle client, push the container-resolved ArtisanBuild\TelltaleClient\Http\TraceHeaderMiddleware onto its handler stack. Turn the header off with the client's trace_header.enabled setting; see Configuration.

Verify the connection

Run the client's doctor command in the NativePHP app:

php artisan telltale:doctor

It checks that TELLTALE_URL and TELLTALE_INGEST are set and valid, that the server is reachable and healthy, and that registration succeeds. Each failure prints a specific message; see Troubleshooting.

Once the app has sent events, the app's entry on the Telltale dashboard shows its latest retained event, and the client version appears under Recently seen client versions.

Before you release

Add the Apple privacy manifest and complete the App Store privacy label and Google Play data safety form. Privacy and data has baseline answers.