TrackNova advertiser integration guide.

1. What the Wrapper Does

1. A visitor clicks a TrackNova tracking link.
2. TrackNova creates a unique click ID and redirects the visitor to the advertiser landing page.
3. The landing URL contains `tn_cid` and/or `cid`.
4. The SDK stores that value in a first-party cookie named `_tn_cid`.
5. When the advertiser confirms a lead, registration, sale, or other action, the page calls `TN.track()`.
6. TrackNova records the conversion event and routes publisher-side pixels/postbacks based on the mappings configured in TrackNova.

2. The TrackNova Click ID

The TrackNova click ID is generated before the visitor reaches the advertiser website. It is not the publisher click ID.

3. Install the Base SDK

Install this script on the landing page and every page where a conversion may be fired. For most websites, install it globally in the site header or tag manager.

<script
  src="{{TRACKING_DOMAIN}}/js/tracknova.js"
  data-client="{{CLIENT_ID}}"
  data-url="{{TRACKING_DOMAIN}}">
</script>

<script
  src="{{TRACKING_DOMAIN}}/js/tracknova.js"
  data-client="{{CLIENT_ID}}"
  data-url="{{TRACKING_DOMAIN}}">
</script>

4. Organization, Offer, and Event

The base tag is organization-level. It identifies your organization, not an advertiser, publisher, or offer.

For normal conversions, TrackNova uses the click ID to find the exact offer. The event key tells TrackNova which action happened on that offer.

5. Fire the Default Conversion Event

Use conversion as the default event when the advertiser only needs to report that a successful action happened.

<script>
  TN.track('conversion');
</script>

Suitable for simple leads, signups, registrations, thank-you pages, or fixed-payout events where TrackNova already knows the commercial values from the offer setup.

6. Send Optional Advertiser References

For lead or registration events, the advertiser may include their own reference values.

<script>
  TN.track('conversion', {
    lead_id: 'LEAD-12345',
    order_id: 'THANKYOU-12345'
  });
</script>

These values help with reconciliation, support, and reporting. They are optional unless agreed in the advertiser setup.

7. Send Sale or Revenue Values

Only send revenue fields when the event is a sale, purchase, order, cart value, dynamic payout, or revshare event.

<script>
  TN.track('conversion', {
    revenue: 150.00,
    sale_amount: 150.00,
    currency: 'USD',
    order_id: 'ORDER-10045'
  });
</script>

8. What Is Required Depends on the Offer Event

TrackNova decides required payload fields from the offer-event configuration.

9. Custom Event Keys

If TrackNova gives the advertiser a custom event key, use it as the first argument.

<script>
  TN.track('kyc_approved', {
    lead_id: 'LEAD-12345'
  });
</script>

The event key must exist as an active event in TrackNova for that offer.

10. Advertiser S2S Postback

Use server-to-server tracking when the confirmed conversion lives in the advertiser backend, CRM, billing system, or an offline workflow.

{{TRACKING_DOMAIN}}/postback?cid={cid}&event=conversion&txid={order_id}&sale_amount={amount}¤cy=USD

{{TRACKING_DOMAIN}}/postback?cid={cid}&event=purchase&txid={order_id}&sale_amount={amount}¤cy=USD

11. Advertiser Pixel URL

Use the pixel endpoint when the advertiser can place an image pixel or iframe on a confirmation page but cannot run the full JavaScript SDK.

{{TRACKING_DOMAIN}}/pixel?cid={cid}&event=conversion&txid={order_id}&sale_amount={amount}¤cy=USD

13. Common Installation Patterns

Thank-you page

Use this when the conversion happens after a form submit, registration, checkout, or payment confirmation.

<script
  src="https://trk.tech-nova.tech/js/tracknova.js"
  data-client="CLIENT_ID"
  data-url="https://trk.tech-nova.tech">
</script>

<script>
  TN.track('conversion');
</script>

Sale confirmation page

<script
  src="https://trk.tech-nova.tech/js/tracknova.js"
  data-client="CLIENT_ID"
  data-url="https://trk.tech-nova.tech">
</script>

<script>
  TN.track('conversion', {
    revenue: window.order.total,
    sale_amount: window.order.total,
    currency: window.order.currency || 'USD',
    order_id: window.order.id
  });
</script>

Single-page app

const payload = {};

if (order?.id) payload.order_id = order.id;
if (order?.total) {
  payload.revenue = order.total;
  payload.sale_amount = order.total;
  payload.currency = order.currency || 'USD';
}

window.TN.track('conversion', payload);

Backend-confirmed but browser-fired

fetch('/api/create-order', { method: 'POST', body: formData })
  .then((response) => response.json())
  .then((order) => {
    window.TN.track('conversion', {
      revenue: order.total,
      currency: order.currency,
      order_id: order.id
    });
  });

14. Browser Network Behavior

When the advertiser website and TrackNova tracking domain are different domains, the browser may send an OPTIONS request before the real POST.

This is normal CORS preflight behavior.

15. QA Checklist

1. Open a real TrackNova tracking link.
2. Confirm the final landing URL contains tn_cid or cid.
3. Complete the advertiser action.
4. In browser DevTools, verify POST /api/tracknova/track returns 200.
5. For pixels, verify GET /pixel returns 200.
6. Confirm the event key is active for the offer in TrackNova.
7. Confirm the conversion appears in TrackNova reporting.
8. Confirm publisher dispatch logs show the expected publisher payload.

16. What Not To Do

• Do not install publisher pixels directly on the advertiser site.
• Do not expose API keys or private tokens in browser code.
• Do not fire TN.track() before the lead, registration, or order is confirmed.
• Do not send revenue values for non-commercial events unless TrackNova asks for them.
• Do not use a publisher click ID as TrackNova cid.
• Do not invent event keys; use the exact event keys configured in TrackNova.

17. When To Use Server-to-Server Instead

Use TrackNova S2S postback when:

• The conversion happens only on the backend.
• The visitor never reaches a browser thank-you page.
• The conversion is a CRM update, subscription rebill, offline sale, or delayed approval.
• You need backend-only validation before firing the event.