Skip to main content

Affiliate SDK

caution

This documentation is in progress.

Our SDK is a JavaScript snippet you can put on your pages. How does it work?

SDK Overview

When a visitor comes to your page, the SDK scans the page for any Organic affiliate links, like https://your-site.organicly.io/aff/r/someid (or, if you've used a custom subdomain, https://organic.your-site.com/aff/r/someid -- see the Custom Subdomain section). It collects these links and sends them to the Organic backend. The backend associates each link with its product and determines which of its offer links is currently the best one to use. It sends these decisions as a response back to the SDK, which then replaces the links on the page with tracking links and inserts a randomized tracking ID. We associate that ID with an impression event, as well as any view and click events that occur.

When a user clicks on the tracking link, the tracking ID is registered by whatever affiliate program the tracking link redirects to. We can then associate any conversion data from that affiliate program with our impression, view, and click events to give a holistic report on how the link is performing on that page. (Of course, with this data, our reporting can provide more general data as well: How is the product performing on the page? How is the product performing across all pages? How is that specific link performing across all pages?)

(In addition to scanning for Organic affiliate links, the SDK also scans for Organic affiliate widget divs. For more information, see the Widgets section.)

An Example

Suppose you have a product with two offer links:

Product X:

You'll have a link for this product on your page that looks like https://your-site.organicly.io/aff/r/product_id. Our SDK will see that link, generate a tracking ID (let's say it's 123), and pass the link and ID to the backend as part of a batched request (i.e., we send one request for all Organic links on the page).

The backend will see that the link is for Product X, and that Product X has two offers. If Offer 1's link is still working, the backend will send a response with https://someAffiliateNetworkLink.com?affiliate_id=100&tracking_id_param=123. If not, it will route to the next best offer, Offer 2, and respond with https://someOtherAffiliateNetworkLink.com?affiliate_id=37&other_tracking_id_param=123. (For details on how the "best" offer is chosen for a product, see the Organic Links section.)

The SDK will take that response and replace[https://your-site.organicly.io/aff/r/product_id with https://someAffiliateNetworkLink.com?affiliate_id=100&tracking_id_param=123 https://someOtherAffiliateNetworkLink.com?affiliate_id=37&other_tracking_id_param=123. It will log an impression event associated with the tracking ID 123 as well as any view and click events.

Later on, our backend will request data from the various affiliate networks you are a part of. If it sees any conversion and revenue data associated with the tracking ID 123, it will know 1) to which link that data corresponds and 2) how to associate that data with our impression, views, and click data for that link.

Wait -- will this break existing third-party tools I use?

We work with you to avoid interfering with third-party tools like Skimlinks or Trackonomics. This typically involves 1) making sure that after we replace your Organic links, our SDK reinitializes any JavaScript the third-party tool uses and 2) we either integrate our tracking ID with the tool or else keep it separate so the two IDs work in parallel.

Yes! The Organic link will redirect the user to the best offer URL using a 307 temporary redirect as described in the Organic Links section. Note, however, that full tracking for such cases is currently still in development.