feat: Add UTM Tracking Support for Developer Attribution

[mfw78]

Problem

The developer community drives significant trading volume through CoW Protocol integrations with zero core team involvement, but we cannot quantify this impact. The Grants Committee needs hard data to demonstrate developer-generated growth to CoW DAO and secure better developer support/resources. Currently, there's no standardized way to track which volume comes from community developers vs other sources.

Suggested solution

Implement automatic UTM tracking in cow-sdk following the [v0.2.0 schema](https://github.com/cowprotocol/app-data/blob/b47139023dea58f8c6d428c49db9d01fd8ad9b54/src/schemas/utm/v0.2.0.json) with these defaults:

{
  "utm": {
    "utmCampaign": "developer-cohort",
    "utmContent": "", // User customizable
    "utmMedium": "cow-sdk@<version>",
    "utmSource": "cowmunity", 
    "utmTerm": "js"
  }
}

Usage examples:

// Default behavior - automatic UTM injection
const order = await cowSdk.createOrder({
  appData: {
    appCode: "myApp"
  }
});
// Result: UTM automatically added alongside existing appData

// Custom utmContent via appData
const order = await cowSdk.createOrder({
  appData: {
    appCode: "myApp",
    utm: {
      utmContent: "my-custom-identifier" // Only override content
    }
  }
});

// Or via SDK configuration
const cowSdk = new CowSdk({
  utmContent: "my-integration-v2" // Sets custom content for all orders
});

Alternatives considered

1. Manual UTM addition: Requiring developers to manually add UTM codes - rejected because it would have low adoption
2. Separate analytics SDK: Creating a wrapper library - rejected as it fragments the developer experience
3. Server-side attribution: Tracking at API level - rejected as it can't distinguish between direct API usage vs SDK usage

Additional context

• cow-py (Python SDK) is implementing similar tracking: [Issue #61](feat/add-utm-codes-to-orders cowdao-grants/cow-py#61)
• Discord discussion revealed consensus on UTM field standardization across all SDKs
• This data is critical for upcoming grant allocation decisions and demonstrating ROI to CoW DAO
• No core team involvement in driving this developer growth - purely community-driven

Acceptance criteria

• UTM fields are automatically populated for all orders created through the SDK
• Existing appCode and other appData fields remain unaffected
• Developers can override utmContent while other UTM fields remain standardized
• SDK version is automatically included in utmMedium field
• Feature can be disabled if needed (though enabled by default)
• Implementation follows the [v0.2.0 UTM schema](https://github.com/cowprotocol/app-data/blob/b47139023dea58f8c6d428c49db9d01fd8ad9b54/src/schemas/utm/v0.2.0.json)
• Tests verify UTM inclusion in appData hash
• Documentation updated with UTM tracking information

[shoom3301]

Hey @mfw78 !
This is already possible, you can do it like:

const appDataParams: AppDataParams = {
  metadata: {
    utm: {
      utmContent: "my-custom-identifier"
    }
  },
}

await sdk.postSwapOrder(tradeParameters, { appData: appDataParams })

Btw, I would recommend using appCode instead, we already have a dashboard with integrators volume (based on appCode value):
https://dune.com/queries/1931075/3185153

[mfw78]

const appDataParams: AppDataParams = {
  metadata: {
    utm: {
      utmContent: "my-custom-identifier"
    }
  },
}

await sdk.postSwapOrder(tradeParameters, { appData: appDataParams })

The point is to have it prepopulated so the default SDK usage can be tracked, without impacting appCode that a developer may use (so that they can subsequently use the query mentioned to track their volume).

Simply put, if it's not default, it's very unreliable to have a developer set it so that volume can be tracked against their default usage.

[shoom3301]

@mfw78 thanks for clarifying!
Anyway, does my example (with appDataParams) work for your case?

[mfw78]

@mfw78 thanks for clarifying! Anyway, does my example (with appDataParams) work for your case?

Hrmm, not really. The point is that, IMO, the SDK should pre-populate the metadata with defaults so that efforts from developers using the bare SDK can be quantified. Also, given that we have the JavaScript and Python SDKs as well right now, it's difficult to attribute developer flow / utilisation between these SDKs/efforts.