TapCub is live — analytics, insights and live chat, free on one platform
Product News

SDK vs API: Differences and When to Use Each for Tracking

SDK vs API for tracking: what each one is, the same purchase event sent three ways, a flash-sale example with retries and duplicates, and rules for choosing.

Lin Zhou Published Nov 20, 2026 11 min read Product News
Sample data: 1,000 orders in 60 seconds. Sending each immediately takes 1,000 requests; a server SDK flushing every 3 seconds sends 20 requests of about 50 events each.Sample data

An API is the contract for sending data to a service; an SDK is a library that calls that contract for you, adding queueing, retries and cleaning. For tracking, send page behavior from the browser SDK and money or account events from your server with an idempotency key, because a retry is only safe when the receiver can recognise the same event.

What you will learn

  • An SDK usually wraps an API; the real choice is where the call runs and how much plumbing you own
  • Send money and account events from your server, where visitors cannot block them, and add an idempotency key such as the order ID
  • Send the session ID with server events so they join the visit that caused them

What is the difference between an SDK and an API?

An API is the contract: the address, the fields and the rules for sending data to a service. An SDK (software development kit) is a library, written for a language or platform, that calls that contract for you. For tracking, the SDK usually does the boring parts: it builds the request, queues events, retries failures and cleans values. The raw API gives you the same endpoint with none of that, so you write those parts yourself.

So "SDK or API" is rarely a choice between two systems. It is a choice about where the call is made (a browser, an app or your server) and how much plumbing you want to own. For the definition of an SDK, see SDK; the step-by-step API call is in send events with the HTTP API.

What does the same purchase event look like through each path?

Take one event: a $19.90 purchase for order 1001. Here it is sent three ways.

Browser SDK. The website script is loaded on the page and one line records the event, in the visitor's browser:

tapcub.track('purchase', { revenue: 19.9, currency: 'USD' });

HTTP API. Your server posts JSON to the business-event endpoint with a server key:

curl -X POST "https://api.pathclue.com/api/v1/track" \
  -H "Authorization: Bearer wck_…" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"event":"purchase","login_id":"u_123","insert_id":"order-1001","properties":{"revenue":19.9}}]}'

Server SDK. A language library (Node.js, PHP, Python, Java or Go) wraps that same endpoint. You call track and the library queues the event, sends it in batches and retries failures.

The first path runs on a device you do not control. The second and third run on a machine you do. That single difference drives most of the trade-offs in the next section.

How do the paths compare?

Browser SDKServer SDKRaw HTTP API
Runs whereVisitor's browserYour serverAnywhere you can send HTTP
CredentialSite script on the page, no secretSecret server key, kept off the pageSecret server key
Can the visitor block or fake it?Yes, a blocker or a script edit can stop or alter itNo: it leaves your serverNo, if sent from your server
Batching and retryHandled by the script, not by youBuilt in: every 3 seconds or at 200 queued events, up to 5 retriesYou write it
Duplicate protectionNot the point for page eventsPass your own key such as the order IDPass your own key
Knows the visitYes, same page and sessionOnly if you pass the session IDOnly if you pass the session ID
Best forPageviews, clicks, scrolls, form viewsOrders, refunds, sign-ups, subscription changesLanguages without an SDK, scripts and back-office jobs

The server key matters most: TapCub's documentation says orders, payments, refunds and sign-ups belong on your server, where they cannot be blocked or faked.

EventPathWhy
Page viewBrowser SDKOnly the page knows it happened
Button click or scroll depthBrowser SDKInteraction data lives in the page
Order paidServer, order ID as keyMoves money; must survive blockers and retries
Refund issuedServer, refund ID as keyHappens in a back office
Sign-up completedServer, session ID if availableConfirmed by your database; joins the visit
Subscription renewedServer or raw API from a billing jobNo visitor present

Rule of thumb: if no visitor is present or money changes hands, send it from your server.

What breaks on each path?

Browser. The page can disappear before the request leaves. MDN describes navigator.sendBeacon() as a way to send data without delaying unload, limits queued data to 64 KiB, and says the unload and beforeunload events are unreliable for sending analytics, recommending visibilitychange instead. A good browser SDK follows that advice, but you still cannot guarantee delivery from a device you do not control.

Server and raw API. The failure is the opposite: a request that actually arrived but whose response never made it back. HTTP defines a method as idempotent if repeating it has the same effect as sending it once. RFC 9110 says a client should not automatically retry a non-idempotent request unless it knows the request is effectively idempotent or can detect that the original was never applied. A tracking POST is not idempotent by itself. Without a key you choose, a safe-looking retry adds a second purchase.

Limits exist on every ingestion API. For example, Google's Measurement Protocol caps a request at 25 events and a 130 kB body, and says it is designed primarily for server-side or trusted environments, directing browser tracking to gtag.js or Tag Manager. Whatever you use, read the limits for your own endpoint before you design batches.

Worked example: a flash sale, retries and duplicates

Sample data. An online shop sells 1,000 orders in 60 seconds during a flash sale, each a $19.90 purchase event of about 300 bytes. Assume a server SDK in default batch mode (flush every 3 seconds or at 200 events, at most 1,000 events and 1 MB per request).

  1. Request count. Orders arrive at 1,000 ÷ 60 = 16.7 a second. In 3 seconds that is about 50 events, far below the 200-event trigger, so the 3-second timer fires first: 60 ÷ 3 = 20 requests of about 50 events. In a send-immediately mode it would be 1,000 requests.
  2. Request size. 50 events × 300 bytes = 15,000 bytes, about 14.6 KiB, well under the 1 MB per-request limit.
  3. Retry window. With exponential backoff starting at 0.5 seconds and doubling, five retries wait 0.5 + 1 + 2 + 4 + 8 = 15.5 seconds before giving up, so a short network blip is absorbed without your code doing anything.
  4. Duplicates. Suppose one batch is accepted by the server but the response times out, and the library resends it. Without an insert_id, each order in that batch is stored twice. For one order, revenue reads $19.90 × 2 = $39.80 instead of $19.90, and across the 50 orders in that batch $1,990 instead of $995. With insert_id: "order-1001" (any key up to 36 characters), the server keeps one event per key and the retry changes nothing.

The lesson is not that servers are risky. It is that a retry is only safe when you give the receiver a way to recognise the same event. The SDK handles queueing, size and retry; you still supply the key.

app.tapcub.com

Requests needed for 1,000 orders in 60 seconds

sample data
Send immediately1,000
Batch every 3 seconds20
Sample data
Sample data: 1,000 orders in 60 seconds. Sending each immediately takes 1,000 requests; a server SDK flushing every 3 seconds sends 20 requests of about 50 events each.

How should you choose?

Use these rules in order.

  1. Does the event move money or change an account? Send it from your server, with an idempotency key such as the order ID. Never rely on the browser for it.
  2. Is it something only the page knows (click, scroll, form view, page load)? Use the browser SDK.
  3. Does your language have a server SDK? Use it instead of writing HTTP calls; it already covers batching, retry and cleaning.
  4. Is it a script, a back-office job or an unsupported language? Call the API directly, and write the retry logic with the key.
  5. Do you need both a server event and its page visit? Send the visit's session ID with the server event so they join; without it the server event does not attach to a visit.

Which path fits each common event?

Applying the rules to eight events a typical product records:

EventPathWhy
Page viewBrowser SDKOnly the page knows it happened, and a missed one is a small loss
Button click or scroll depthBrowser SDKInteraction data lives in the page
Form viewedBrowser SDKSame reason; do not send what the visitor typed
Order paidServer, with the order ID as keyIt moves money and must survive blockers and retries
Refund issuedServer, with the refund ID as keyHappens in a back office, not in a visitor's browser
Sign-up completedServer, with the session ID if availableConfirmed by your database; joins the visit that caused it
Subscription renewedServer or raw API from a billing jobNo visitor is present at all
Nightly import of past recordsRaw API or import toolA batch job, not a live visit

Notice that the last four never involve a visitor's browser at all. For those, the question "SDK or API" is only about whether your language has a server SDK.

How do you send the same event with TapCub, and check it arrived?

TapCub supports all three paths. The checkout example from above, step by step:

  1. Put the website script on the site (code in Web analytics › Configuration › SDK code) and record page behavior with tapcub.track.
  2. For the purchase, create a key in Configuration › Settings › API keys and include the Server track scope. The key starts with wck_ and is shown once.
  3. Send the event with POST /api/v1/track, from a server SDK or the curl call above. Add debug=1 first: it validates the event and answers per event without storing anything.
  4. Read the response: accepted counts events that passed validation and rejected carries a reason, such as a missing event name. Reuse the same insert_id if your code retries; a resend does not add a row, and duplicates are recognised for one day after the first copy is stored, so retry promptly.
  5. Open Web analytics › Events or All-platform analytics › Data › Events & properties to see the purchase. Pass the visit's session ID if you want it joined to the pageview; an event without one stays in the event table and is not counted as a new visit. A raw HTTP call has no built-in retry, so write it yourself.

FAQ

Is an SDK better than an API?

Neither is better in general. An SDK is a wrapper around an API that adds queueing, retry and cleaning. Use an SDK when your language has one; call the API directly for scripts or unsupported languages, and add the retry and idempotency key yourself.

Does an SDK use an API?

Usually yes. Server SDKs commonly wrap a single HTTP endpoint. The SDK builds the request, batches events and retries failures; the API is the contract those requests follow.

Should I track purchases in the browser or on the server?

On the server. Browsers can be blocked, altered or closed before the request leaves. A server-side purchase event, with an idempotency key, avoids undercounts from blocking and double counts from retries.

Why do I need an idempotency key?

Because a request can reach the server while its response is lost, and a retry then sends it again. With a key such as the order ID, the server keeps one event per key. Without one, revenue can be counted twice.

Can I use both the SDK and the API in one project?

Yes. Use the browser SDK for page behavior and the server for money events, and send the session ID with the server event so the two join in one visit.

Sources

Filed underProduct News

Was this article helpful?

We use your answers to fix and expand this page.

Lin Zhou

Product Experience Specialist

Writes about product experience, practical workflows, and growth, turning complex processes into clear steps for everyday decisions.

Send events from the browser and your server

One project, one visitor model: website script for page behavior, server keys for orders and sign-ups, and a debug mode to verify before you go live.

See your data clearly. Find your growth.

Every click, backed by data. Install one line of code and see your first numbers in a minute.

No credit card · Free plans for analytics and chat · Cookieless analytics