Track Dub referral links in Japanese and English without breaking referral IDs

When Japanese and English articles point to the same referral link, the link alone does not distinguish their language or placement. I tested a URL builder that labels both with UTMs while preserving the issued referral path and existing referral parameters.

The experiment was run on September 30, 2026. It checks URL construction locally using example.com fixtures. It does not issue links through Dub’s API, test redirects, verify purchases, or establish commission attribution. The tests generate no referral clicks or signups.

#Separate traffic from confirmed commissions

A click and a confirmed commission represent different events. A reader may leave without signing up, or continue using a free plan. Refund and cancellation rules also vary by program, so a sale event is not necessarily a finalized payout.

For this publication, the review sequence is article views, referral clicks, leads, sales, and confirmed commissions. Define click rate as referral clicks divided by relevant article views, and lead rate as leads divided by relevant link clicks, using matching periods and scopes. Adding UTMs does not collect every input needed for those calculations.

Dub documents filtering analytics by UTM values and combining that view with Conversions to inspect signups and sales. A publisher’s URL builder cannot instrument the vendor’s conversion events. Dub UTM analytics announcement

#Keep the issued referral URL as the source

Start with enrollment and the referral URL issued by the program. Recreating a short link from a product’s ordinary website URL can lose the original referral identifier. Add editorial labels to the issued URL instead.

The fixture is https://example.com/ref/demo?ref=keep#pricing. I set explicit expectations that /ref/demo, ref=keep, and #pricing survive construction. That proves what our code preserves, rather than what a vendor’s attribution system will do.

In the current site implementation, Circleback has a verified issued referral link; Dub uses an ordinary official-site link because this account is not enrolled in its program. Dub’s public enrollment page lists 30% per sale for one year. This does not mean this publication currently earns that commission. Dub’s official program page

#Use one naming convention for both languages

I use the article slug as the campaign and put language and placement in utm_content. A translated title would be a poor campaign identifier: an editorial title change would create a different campaign label.

Use body for a contextual link and footer for the service section after an article. Restricting values avoids mixing JA, jp, and Japanese for the same language. Reader emails and customer names have no role in these labels. URLs can appear in histories and access logs, so article-level identifiers are sufficient.

#Build parameters with the URL API

Appending ?utm_source=... to a string fails when the URL already has a query. I edit parameters with URL and URLSearchParams instead.

import { buildReferralUrl } from './referral-utm.mjs'

const url = buildReferralUrl(
  'https://example.com/ref/demo?ref=keep#pricing',
  {
    locale: 'ja',
    slug: 'circleback-webhook-action-items',
    placement: 'footer',
  },
)
console.log(url)

The result is:

https://example.com/ref/demo?ref=keep&utm_source=sakimyto.com&utm_medium=affiliate&utm_campaign=circleback-webhook-action-items&utm_content=ja-footer#pricing

Existing UTM values are replaced with this convention. searchParams.set avoids duplicate utm_content entries while retaining unrelated parameters and the fragment. The function accepts HTTPS URLs without embedded credentials, ja/en locales, body/footer placements, and lowercase alphanumeric article slugs separated by hyphens.

#What the local tests establish

Generating Japanese and English variants from one input changes utm_content from ja-footer to en-footer. The path, referral value, fragment, and campaign stay the same. Tests also verify that an existing UTM value is replaced rather than duplicated.

Relative paths, HTTP URLs, javascript: URLs, and URLs with embedded credentials are rejected. Unsupported languages, unknown placements, and a slug such as ../private also fail. These checks keep editorial inputs consistent; they cannot turn an arbitrary URL into a valid program referral.

Download the three shared companion files into one directory. Run bun demo.mjs, or node demo.mjs with Node.js 22+.

• UTM builder
• Executable demo
• Task adapter imported by the demo

The demo uses a fixture without a fragment and prints both language variants. Add #pricing to its input to reproduce the fragment-preservation example.

#Applying labels to a real referral link

Dub documents passing short-link parameters to the destination, with short-link values taking precedence when a destination parameter has the same name. Avoid overriding any parameter the program uses for referral identity. Dub parameter forwarding announcement

Check program rules before adding UTMs to an issued link. If the program provides an approved testing method, inspect the final referral identifier, UTM values, and corresponding click record. Do not manufacture self-referral purchases to test payouts; program-specific restrictions still apply.

The site currently publishes the original verified Circleback URL. This local URL experiment and vendor-side attribution verification remain separate. A structurally correct URL is not evidence that a commission was attributed correctly.

#Using the data to choose further articles

Measurement also needs context if AI is going to help with the next decision. Instead of recording that an article “did well,” retain its slug, language, reporting period, views, clicks, and confirmed commissions separately. That gives a later editorial review a basis for distinguishing reach from adoption decisions. This URL construction experiment does not collect those performance figures.

After publication, first check whether each language attracts readers searching for the problem addressed. If views do not lead to clicks, review whether the article gives enough information to decide on the service. If clicks do not lead to signups or sales, investigate product fit, pricing, and setup effort. A small number of clicks cannot establish a reliable language-level conversion difference.

The Circleback webhook experiment tests concrete integration decisions, including missing owners and replay handling. That is the editorial standard for subsequent SaaS articles: give readers evidence they can use to judge whether the workflow fits their own operation.