Tracking Free Licenses from Atlassian Marketplace

Goal

Setting standardized traits early allows you to track when instances convert from free licences to evaluation or paid licenses.

Why This Matters

When a user installs your app with a free license, Atlassian Forge's context object gives you minimal data; however, it does provide:

cloudId (e.g. 99993312-1324-4a03-b822-2765656c70be4)
sitedomain (e.g. acme.atlassian.net)

By setting a few consistent traits via your Accoil group call, you can:

Humanize cloud instances (no more cloudId confusion)
Seamlessly match users as they upgrade to evaluation or paid
Unify reporting across license types with shared traits

Required Traits to Send via Group Call

Send the following traits when you first detect a free license install:

accoil.group({
  group_id: "<cloudId>",
  traits: {
    "am.contactdetails.company": "acme",
    "am.cloudsitehostname": "acme.atlassian.net",
    "am.licensetype": "free"
  }
});

Trait Details

Trait Name	Example Value	Description
`am.contactdetails.company`	`acme`	Just the subdomain (not the full domain). Makes the org name readable and helps unify across license types.
`am.cloudsitehostname`	`acme.atlassian.net`	The full instance domain. Helps identify the specific Jira/Confluence cloud instance.
`am.licensetype`	`FREE`	Use `"FREE"` here. When a user converts to a paid or evaluation license, this will update to `"evaluation"` or `"paid"` from the Atlassian Marketplace connector.

Why This Structure Works

When a free license user upgrades:

The Atlassian Marketplace connector will start sending the same traits with updated values (e.g. license type becomes "evaluation" or "paid").
Because you're already tracking am.contactdetails.company and am.cloudsitehostname, these traits line up perfectly, and you can easily identify the sites and companies using your product.