Button Links Integration

An overview of using Button Links to power attribution.

Button Links allow you to create a link that utilizes Button's routing and attribution systems to help a user shop in-app or on the web.

Here's an example:

https://r.bttn.io? \
  btn_url={https%3A%2F%2Fwww.brandwebsite.com} \
  &btn_pub_user={user_id_here} \
  &btn_ref={org-0000000000000000}
https://r.bttn.io?btn_url=https%3A%2F%2Fwww.brandwebsite.com&btn_pub_user=user-123&btn_ref=org-0000000000000000

Button Links accept the following query string parameters. All links must only contain ASCII characters and have properly encoded query strings.

FieldRequired?Definition
btn_urlYesThe target Brand URL (url-encoded, including https)

e.g. https%3A%2F%2Fwww.brandwebsite.com
btn_refYesYour Button Organization ID (always starts with the prefix org-).

e.g. org-0000000000000000

This can be found in your Button dashboard.
btn_pub_userRequired for user rewardsYour user’s unique identifier. This value will be passed back to you in webhook requests associated with any downstream Brand activity such as orders or app-installs. Must be under 256 characters.

e.g. user-12345

Note: If you reward users for shopping activity you must include this value in order to know which user to reward.
btn_pub_refNoA Publisher reference value (e.g. click ID, campaign ID).

This value will be passed back to you in webhook requests associated with any downstream Brand activity such as orders or app-installs. Must be under 512 characters (decoded).

e.g. click-abc123
btn_desktop_urlNoA URL to redirect to if the user is on desktop. Leverage this parameter if you have a desktop network affiliate link you would like to use, otherwise exclude this parameter.

e.g. https://youraffiliateurl.com/tracking-info

Passthrough Values

Similar to how Publishers can use Button's iOS / Android SDK and have passthrough values persisted through Button, Publishers can pass a user ID or reference value on a Button Link.

Simply add the btn_pub_user parameter to pass through a user ID, or add the btn_pub_ref parameter to pass through a reference value (e.g. click ID, campaign ID).

Here's an example Button Link:

https://r.bttn.io? \
  btn_url={https%3A%2F%2Fwww.brandwebsite.com} \
  &btn_pub_user={user_id_here} \
  &btn_pub_ref={your_passthrough_value} \
  &btn_ref={org-0000000000000000}
https://r.bttn.io?btn_url=https%3A%2F%2Fwww.brandwebsite.com&btn_pub_user=user-123&btn_ref=org-0000000000000000&btn_pub_ref=your-ref

Button Links on Desktop

Button Links work equally on mobile & on desktop, but if you prefer to use an alternative link when a user is on desktop you can do so by providing a btn_destkop_url parameter — Button will then forward desktop users to that URL.

https://r.bttn.io?\
   btn_url={https%3A%2F%2Fwww.brandwebsite.com} \
   &btn_ref={org-0000000000000000} \
   &btn_desktop_url={https%3A%2F%2Fyouraffiliateurl.com%2Ftracking-info}
https://r.bttn.io?btn_url=https%3A%2F%2Fwww.brandwebsite.com&btn_ref=org-0000000000000000&btn_desktop_url=https%3A%2F%2Fwww.affiliate-url-example.com

If you want Button to power desktop affiliation:

  • Simply use the Button Link on desktop as you would on mobile web (i.e. do not include the btn_desktop_url parameter).

Additional ways to use Button Links