Instance-Level Tracking in Forge

Why Use Instance-Level Tracking?

By default, analytics events in Forge apps use the Atlassian accountId, meaning every user is tracked separately. This gives you user-level visibility — but at a cost:

• High MTU counts, which directly increase analytics cost
• GDPR complexity, since every user becomes a data subject
• Increased compliance risk, even if no emails are sent

Instead, instance-level tracking assigns the same ID to all users in the same site, using the cloudId. This provides:

✅ One tracked “user” per instance

✅ Major MTU cost reduction

✅ Simplified privacy and compliance

🔁 How It Works

In your analytics utility function:

export const userIdFromContext = (context) => {
  if (process.env.ANALTYICS_USER_ID_OVERRIDE?.toLowerCase() === "true") {
    return context.cloudId;  // All users in instance share this ID
  } else {
    return context.accountId; // Default: per-user tracking
  }
};

Set the override via environment variable:

forge variables set ANALTYICS_USER_ID_OVERRIDE true

Now, all analytics calls will report user_id = cloudId, regardless of which user triggered the event.

📦

Working Example Available

The following code is available in our sample app available on GitHub.

🔗 View the full Forge Analytics Example on GitHub

💸 Cost Reduction Example

Result: Up to 98% reduction in MTU-related billing.

Note: Instance-level tracking reduces MTUs, but some providers (like Segment) apply quotas based on event volume too. For example, Segment allows 250 events per MTU per month. So if you're paying for 1,000 MTUs, you can send up to 250,000 events. If you send 500,000 events, even with only one user ID, you'll be billed for 2,000 MTUs.

🛡️ Privacy Benefits

With instance-level tracking:

• No individual account IDs are stored
• No per-user analytics records are created
• Simplifies your privacy policy and reduces PII exposure

A typical privacy policy entry:

## Analytics

We collect instance-level analytics to improve product quality.  
No individual user data is tracked or stored.

⚙️ How to Enable It

1. Set Environment Variable

For development:

forge variables set --environment development ANALTYICS_USER_ID_OVERRIDE true

For production:

forge variables set --environment production ANALTYICS_USER_ID_OVERRIDE true

2. Confirm It’s Active

forge variables list

Look for:

ANALTYICS_USER_ID_OVERRIDE: true

3. Test in Logs

With debug mode enabled:

forge variables set ANALYTICS_DEBUG true
forge deploy
forge logs --tail | grep "Analytics"

You should see:

{
  "user_id": "a1b2c3d4-cloudId",  // Same for all users in instance
  "event": "Form Created"
}

✅ What You Still Get

Even with instance-level tracking, you can still measure:

• Feature usage at the instance level
• Workflow adoption across accounts
• Subscription or licensing status
• Object counts and growth (via snapshot metrics)

🚫 What You Give Up

• You won't see which user did what
• You can’t segment by user type or role
• No user-specific journeys or funnels

This tradeoff is often worth it in B2B Forge apps, where product usage happens at the team or org level — and where privacy and cost efficiency matter more than identifying individual users.

Summary

Instance-level tracking is a lightweight, configurable approach that gives you:

• 90%+ reduction in analytics costs
• Simpler privacy posture
• Actionable insights at the account level

Enable it with a single setting:

forge variables set ANALTYICS_USER_ID_OVERRIDE true

And for a full working example, check out:
🔗 https://github.com/sherlockscore/forge-todo-example-with-analytics-app