⏩Start Here

Welcome! This guide will help you start running ads on your website or mobile app.

1. Onboarding

To get started, please reach out to the Spindl team to get your account approved as a Publisher. As part of that, you will need provide a Wallet Address for earnings to be sent to.

2. Set up a placement

Next, you'll need to set up at least one Placement. A placement is simply a place in your app where you show an ad - you can create as many as you need. When you create a Placement, you need to pick a Creative Type (full list here).

If you need a custom creative type for your placement, reach out to the Spindl team, and we can create it for you.

3. Technical Integration

There are three ways to integrate ads into your product. Most customers prefer the API approach for native integrations, and the React SDK for simple image-based ads.

API

To use the API, you must first generate a Publisher API Token (you can find that on the Settings screen).

This API Token should be treated as a secret, and not shared in any public-facing code.

Next, there are two APIs you will need to call.

1. Fetch Recommendations

   1. GET https://e.spindlembed.com/v1/render/{publisher_id}

   2. Headers

      1. X-API-ACCESS-KEY : Publisher API Key, from the Settings tab

   3. Path Params

      1. publisher_id: Text, provided by the spindl team

   4. Required URL Params

      1. placement_id: Text, from the Placements tab

      2. address: Text, the wallet address, in the form of 0x...

      3. limit: Numerical, the number of recommendations to return (usually this is 1)

   5. Optional URL Params

      1. chain_id: Numerical, the chain ID where this unit is being rendered

   6. Response:

{
  "items": [
    {
      "id": string,
      "impressionId": string,
      "type": string,  // specifies format of unit (card, iframe, discord)
      "title": string,
      "context": { // reason for returning unit (social context, onchain activity)
        "text": string
      },
      "description": string,
      "imageUrl": string,
      "imageAltText": string,
      "ctas": [
        {
          "title": string,
          "href": string
        }
      ]
    },
    ...
  ]
}

1. Post Impressions (record anytime a recommendation is shown on screen)

   1. POST https://e.spindlembed.com/v1/external/track

   2. Headers

      1. X-API-ACCESS-KEY : Publisher API Key, from the Settings tab

   3. Body (JSON)

      1. type: Text, should be impressionor click

      2. impression_id: Text, the impressionId from the API above

   4. Response: Status Code 200

React SDK

Spindl provides a SDK for React to make it simple to drop in ads throughout your site. For this, you will need your Publisher ID and a Placement ID, both available on the Placements tab.

1. Install the React SDK (NPM Link)

npm i @spindl-xyz/embed-react

1. Add to your site

 <BannerEmbed
    publisherId="my_website" // required (get from Spindl team)
    placementId="article_sidebar" // required (get from Spindl team)
    style={{
        width: "970px",
        height: "250px",
    }} // recommended to add desired width/height
    address={"0xSpindl"} // optional, can also be a list of addresses (["0x123", "0x456"])
    properties={{
        chain_id: 8453,
    }} // optional, you can pass in JSON blob with contextual information (ie, category of article) for better targeting
/>

If there are no ads available, this will show up empty.

iFrame

Spindl provides a direct iFrame link, to make it simple to drop in ads on your Website or Mobile App. For this, you will need your Publisher ID and a Placement ID, both available on the Placements tab.

<iframe
    width="800"
    height="400"
    src="https://e.spindlembed.com/v1/serve?publisher_id=my_website&placement_id=article_sidebar&address=0xSpindl"
></iframe>