# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.spindl.xyz/spindl/ads/start-here.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.