# 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](https://docs.google.com/spreadsheets/d/181QVJ3_HMJpHC2yk0F112DmguAHkzQCrLS0Ff9TKA74/edit?gid=0#gid=0)).

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.

{% tabs %}
{% tab title="API" %}
To use the API, you must first generate a Publisher API Token (you can find that on the [Settings](https://app.spindl.xyz/settings) screen).

{% hint style="warning" %}
This API Token should be treated as a secret, and not shared in any public-facing code.
{% endhint %}

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](https://app.spindl.xyz/placements)
      2. `address`: Text, the wallet address, in the form of 0x...
      3. `limit`: Numerical, the number of recommendations to return (usually this is 1)
      4. `country`: The country where the request originated from, should be a [2-letter country ](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)code.
         1. (If you are using Cloudflare, you can pass in `CF-IPCountry` to this field directly)
   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
        }
      ]
    },
    ...
  ]
}
```

2. **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 `impression`or `click`
      2. `impression_id`: Text, the `impressionId` from the API above
   4. Response: Status Code 200
      {% endtab %}

{% tab title="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](https://app.spindl.xyz/placements).

1. Install the React SDK ([NPM Link](https://www.npmjs.com/package/@spindl-xyz/embed-react))

```bash
npm i @spindl-xyz/embed-react
```

2. Add to your site

```tsx
 <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
/>
```

{% hint style="info" %}
If there are no ads available, this will show up empty.
{% endhint %}
{% endtab %}

{% tab title="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](https://app.spindl.xyz/placements).

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

{% endtab %}
{% endtabs %}