Logo

README

piratepx consists of a single endpoint that you request to increment a count: 

https://app.piratepx.com/ship?p={{PROJECT_ID}}&i={{COUNT_IDENTIFIER}}

Usage

Website

If you’re adding piratepx to a website, simply drop this URL into an <img> tag: 

<img src="https://app.piratepx.com/ship?p={{PROJECT_ID}}&i={{COUNT_IDENTIFIER}}" />

If you leave out the count identifier (i in the query string), the Referer header is parsed for a URL path. For example, https://www.yoursite.com/about?query=string#hash is parsed as /about. This allows you to add the <img> in one place on the website (like the footer) without having to configure the count identifier for every page.

However, a few things to keep in mind:

  • Browsers are increasingly using the Referrer-Policy strict-origin-when-cross-origin by default, as explained in this helpful article. This results in / being counted as the identifier regardless of the actual URL path. You can either override the browser’s default by setting your own Referrer-Policy, or explicitly set the count identifier in the query string.
  • Some websites suppress the Referer header from being sent (like GitHub), in which case you will need to explicitly set the count identifier in the query string.
  • If the website includes lots of unique identifiers in the URL path (think a SaaS app with record IDs), it’s highly recommended to explicitly set a count identifier that’s more generalized for the route. For example, /users/:user_id instead of ending up with separate counts for /users/123, /users/456, etc.

Anywhere Else

If you’re adding piratepx to a mobile app, server-side API, CLI, or other non-HTML context, simply use your preferred request library in the language of your project. Here are a few examples...

JavaScript’s fetch: 

const query = new URLSearchParams({
  p: '{{PROJECT_ID}}',
  i: '{{COUNT_IDENTIFIER}}',
})

fetch(`https://app.piratepx.com/ship?${query.toString()}`)

PHP’s file_get_contents: 

$query = http_build_query(array(
  'p' => '{{PROJECT_ID}}',
  'i' => '{{COUNT_IDENTIFIER}}'
))

file_get_contents("https://app.piratepx.com/ship?{$query}")

curl: 

curl -G -d 'p={{PROJECT_ID}}' --data-urlencode 'i={{COUNT_IDENTIFIER}}' https://app.piratepx.com/ship

Recipes

Want to see how others have implemented piratepx in a specific framework or language? Or maybe you’ve already added it to a project and want to share your knowledge?

There’s a growing collection of such recipes on GitHub Gists with the tag #piratepx.

Options

Param Type Validation Description
p UUID Required The ID of your project.
i String Max length: 255 The count identifier to increment. If not set, the Referer header is parsed for a URL path.

Response

A 1×1 pixel, 37 byte transparent GIF is returned regardless of whether the request was successful or ran into an error.

piratepx