Featuring corporate logotypes in READMEs, sites & docs is one of the most common & efficient ways of getting commercial funding in open source. However, upselling and managing this offering has been entirely manual & coordinated over email - it's painful for everyone.

Until now. Introducing Polar Ads; a new - built-in - subscription benefit you can setup to streamline & automate this offering to your Polar subscribers.

1. You integrate Polar Ads (README, site/docs) once - it's easy.
2. Create subscription benefits for each placement, e.g Gold Sponsors (640x300px), Silver Sponsors (440x200px) etc.
3. Your sponsors can now manage & upload their own assets in light- and dark mode and the right dimensions. It's synced across your real-estate automatically.

Easy setup

Let's get you setup so you can get more time back to write code & posts vs. emails...

Creating the subscription benefit(s)

1. Goto Subscriptions in your creator dashboard on Polar and then click Edit tier on your Free tier. So you can easily test this yourself without paying during setup :-)
2. Click New Benefit (See below)

Let's create our first ad placement for Gold Sponsors. Offering logotypes/assets that are 640 x 300 pixels.

1. Select Ad as the benefit type
2. Name the benefit & how it's upsold, e.g Gold Sponsor Logo Placement
3. Specify the dimensions
4. Click Create

PS. You can of course create unique benefits for README vs. site vs. docs placements. Specifying that in the benefit label or tier description.

Awesome! We can see the benefit in our tier preview and it looks great - so let's hit Save Tier to update the free tier.

Now, let's pretend to be sponsors. On your public Polar page potential subscribers can now clearly see the benefit being upsold.

Gold Sponsor Logo Placement for free? How could we not subscribe. Let's do it (use an incognito window to subscribe using another email).

Once subscribed, we immediately gain access to the benefits and it's super easy to activate & customize our logo assets.

1. Click on the benefit, e.g Gold Sponsors Logo Placement
2. Upload light- and dark mode images matching the dimensions
3. Provide a link and optional tagline

Now, they will be automatically synced and featured in READMEs, sites & docs. You only need to integrate support for that, but it's easy & only required once - we'll do it now.

README Integration

1. Goto Subscriptions > Benefits in your Polar creator dashboard
2. Click on Gold Sponsors Logo Placement
3. Copy the embed code
4. Add it to your README.md exactly where you want the logotypes to be embedded

In our example you might notice that the embed code already has an ad for Gold Sponsors - it's the one we uploaded as a subscriber earlier. That's great since you'll directly be up and running, but it's still manual...

Don't worry. Notice that the code is wrapped in Polar HTML comments (this is the default embed code without any current sponsors). Polar offers a GitHub Action which uses these comments as a basic templating language: Creating new commits to update the contents upon changes in subscribers.

Let's automate it now & see some magic 🪄

Creating an access token

You'll first need a personal access token to the Polar API.

1. Goto your settings
2. Scroll down to Access Tokens
3. Name the token, e.g README ads
4. Click Create
5. Copy the access token (save it somewhere safe too)

Save the access token as a GitHub action secret

Now, let's go over to GitHub to add our newly created access token as a secret to the repository's actions.

1. Goto the Settings of the repository you want to automate the README for
2. Click on Secrets and variables > Actions
3. Create a new secret named POLAR_API_TOKEN with the access token as the value

Setup the Polar action

Last step: Creating the Polar action (we like to call it Polarify) to run on each commit and hourly - feel free to customize this of course.

name: Polarify

# Example action of how to use the polarsource/actions/polarify action and auto-commiting the results to the repository.

on:
  # Run after every push
  push:
    branches: ["main"]

  # Hourly
  schedule:
    - cron: "0 * * * *"

  # Allow to trigger manually from the GitHub Actions Web UI
  workflow_dispatch: {}

jobs:
  polarify:
    name: "Polarify"
    timeout-minutes: 15
    runs-on: ubuntu-22.04

    permissions:
      # Give the default GITHUB_TOKEN write permission to commit and push the changed files back to the repository.
      contents: write

    steps:
      - name: Check out code
        uses: actions/checkout@v3

      - name: Polarify
        uses: polarsource/actions/polarify@main
        with:
          path: "README.md"
        env:
          POLAR_API_TOKEN: ${{ secrets.POLAR_API_TOKEN }}

      - uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: Update polar comments
          branch: main

1. Create the file .github/workflows/polarify.yaml in the root of the repository
2. Copy-paste the snippet above
3. Commit & push
4. Run the action manually and... 😍

Demo

Amazing! Using the same steps above, I created an example over at @birkjernstrom/dotfiles. It's a silly example, but works like a charm and illustrates the power.

Now, I could easily add more types of this benefit in different dimensions and placements – upselling & automating them seamlessly 😍

Integrate everywhere (Site, Docs etc)

Polar is built on our Public API & TS SDK. So integrating this benefit on your site, docs, service or elsewhere is a breeze.

1. Goto Subscription > Benefits in your creator dashboard on Polar
2. Copy the Identifier of the desired ad benefit
3. Integrate anywhere & fully custom

curl -s -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    "https://api.polar.sh/api/v1/advertisements/campaigns/search?organization_name=YOUR_GITHUB_USERNAME_HERE&platform=github&subscription_benefit_id=YOUR_BENEFIT_ID_HERE"

{
  "items": [
    {
      "id": "b13e9e4b-cbad-4c27-b421-e4993a984a5c",
      "subscription_id": "44df54b2-05e7-4884-8b13-637036c21c41",
      "subscription_benefit_id": "4da75f02-1507-43dc-9167-10adfa4fb6b2",
      "views": 30,
      "clicks": 0,
      "image_url": "https://7vk6rcnylug0u6hg.public.blob.vercel-storage.com/Logotype_blue_small-Bo8grIZgHSOMQk3BnwmoT5Sds6tE7N.png",
      "image_url_dark": null,
      "text": "Join Polar now!",
      "link_url": "https://polar.sh/"
    },
    {
      "id": "94c1676c-db08-4489-b4b4-e25beadf2542",
      "subscription_id": "922bcc1d-b570-42a6-be16-52c868b81576",
      "subscription_benefit_id": "4da75f02-1507-43dc-9167-10adfa4fb6b2",
      "views": 12,
      "clicks": 0,
      "image_url": "https://7vk6rcnylug0u6hg.public.blob.vercel-storage.com/Frame%203-lOg2u5gntqF3RuL3cso7Upg9w03dbT.png",
      "image_url_dark": "https://7vk6rcnylug0u6hg.public.blob.vercel-storage.com/Frame%202-fcOO2r4HRJSRYthVDEK1Tf4ZTajDN1.png",
      "text": "Hello world!",
      "link_url": "https://polar.sh/zegl"
    }
  ],
  "pagination": {
    "total_count": 2,
    "max_page": 1
  }
}

You can be creative with this and setup unique ad benefits per surface area, e.g docs, site or even write custom scripts to generate YouTube & Twitch assets.

Offering more and more exposure with more premium subscription tiers. We can't wait to see how you use it 🙂

Sponsors in Polar Posts

One last thing... Another great surface area to thank, reward and incentivise more sponsors is in posts & newsletters. So we made it plug-n-play within Polar.

Just select the ad benefit you want to embed within a post and that's it. In case of multiple sponsors the benefit will automatically round robin between them per page view or email (newsletter).

It's a win-win. We've seen since launch that frequent posts have been super valuable in driving more subscribers & converting to paid. So by writing posts to keep your community in the loop you:

1. Build a larger & more engaged community
2. Convert more into paid subscribers
3. Create a more attractive newsletter & posts for commercial sponsors

Polar Ads will spare your inbox and remove the overhead of manually updating sponsors. All while providing sponsors with a better experience to self-manage their benefit & assets. So we can't wait to see the impact of it in the wild.

Don't hesitate to share your feedback or questions with us. You're welcome to join our Discord and chat directly with the team & fellow developers using Polar.

Until next time, keep building.

Friendly reminder: Followed this guide? Make sure to disable the ad benefit in your free tier & enable it instead across your paid subscription tiers as desired. :-)