Skip to Content
Torque Lift Docs

Tracking is a pull request

How Torque Lift adds event tracking as a pull request, the tracking plan file, property types, what is never tracked, and consent.

Torque Lift writes a tracking plan and the code that sends it, in your repo. Your team reviews the plan first, then the code, and a person merges each.

How tracking gets into your app

Torque Lift drafts a plan

A short list of events, with the properties each carries and where each one fires. The first pull request lists up to 10 events and changes no app code.

Your growth lead approves it

Merging the plan's pull request is the approval. Nothing is written until then.

Torque Lift writes the code

In a sandbox with no data credentials and no GitHub token, Torque Lift adds the tracking to your files, then runs your own typecheck, tests and build before the pull request opens.

A person on your team merges

Your CI runs on the pull request, and Torque Lift's guards check it for personal data and for files outside the plan's scope. The pull request lists what to set in production before you merge.

The tracking plan file

The plan is one file in your repo, torque-lift/tracking-plan.yaml. It is the record of what your app sends, and the pipeline checks every event against it.

torque-lift/tracking-plan.yaml
version: 3
app: web
scope: ["app/**", "components/**"]
user_id: {type: id, source: "session.user.id"}
buckets: [onboarding, projects, billing]
pages:
  - {route: "/welcome", bucket: onboarding}
  - {route: "/projects/[id]", bucket: projects}
events:
  Project Created:
    bucket: projects
    stage: activation
    properties:
      project_id:    {type: id, source: "project.id", required: true}
      template_used: {type: boolean}
  Checkout Started:
    bucket: billing
    stage: monetization
    properties:
      plan_tier: {type: enum, values: [pro, team]}
      currency:  {type: currency}
      value:     {type: number, min: 0}
KeyWhat it does
versionOne more than the plan on your default branch. A change to the plan only adds.
scopeThe folders where tracking calls may go. A call anywhere else fails the check.
bucketsGroups of events by area of your app, up to 12.
stageOne of acquisition, activation, engagement, monetization or referral.
eventsNamed as an object, then a past-tense action, in Title Case: Project Created. Properties are snake_case, up to 25 an event.

Torque Lift writes the Segment spec's track, identify and page calls (screen on Android and iOS). The pull request's lint checks the plan's names, types and limits before it opens.

What a property can hold

Every property has one of these types. There is no free-text type, so URLs, query strings and typed text have nowhere to go.

TypeHolds
enumOne of the values the plan lists, in snake_case
booleanTrue or false
integer, numberA number, with an optional minimum and maximum
idAn opaque internal ID, up to 64 letters, digits, dashes and underscores. The plan names where it is read from
timestampA date and time in UTC
currencyA three-letter code, such as USD
routeA route template such as /projects/[id], never a real URL
versionA version number or commit SHA

What Torque Lift never tracks

These names are refused wherever they appear, even when a plan declares them. Matching ignores case and underscores, so first_name and FirstName are the same name.

KindExamples
Direct identifiersemail, name, username, phone, address, birthday, age, gender
Free textmessage, comment, note, description, query, search, title
Networkip, ip_address
Locationcity, region, latitude, longitude
Secrets and paymentpassword, token, api_key, card_number, cvv

The same list is enforced twice: when Torque Lift writes the plan and the code, and again as events land in your bucket. A value that looks like an email, a phone number or a card number is removed even if its property is allowed. More in Data and privacy.

Torque Lift's tracking sends nothing from a visitor's browser until your app records that they've agreed to analytics. Your app decides when that is. See setAnalyticsConsent for the call.

Changing the plan later

To track something new, Torque Lift opens a new pull request that raises the plan's version by 1 and adds the event, with the code to send it. The same checks run, and a person on your team merges it.

Check that events arrive

In your console, the Data page shows events in the last day, how fast they become queryable, which planned events are firing, and what was turned away and why.

On this page