.
**To do this, you will need:**
* Spindl API Key
* Properly Formatted events (you can send individual event or an array)
* for each event, you can define an object:
[
{
"type": "CUSTOM", // required (use the default "CUSTOM")
"data": {
"name": "Your Event Name", // required.
"properties": { ... } // optional data can be passed as JSON here
},
"identity": {
// either address or customerUserId is required to help us identify a user
"address": "0x...",
"customerUserId": "test@gmail.com"
}
}
]
Below are several examples for sending an **array** of events to our API:
## Send Custom Events
`POST` `https://spindl.link/events/server`
Sending Custom events via API
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ------------- |
| X-API-Key\* | String | The API token |
#### Request Body
| Name | Type | Description |
| ---------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \* | Array | array of events is required to be passed in. Please pass in a array of objects with the following keys:
type (required): string
use "CUSTOM" here
name (required): string
Min 3 & max 100 characters. Must be lower/uppercase alphanumeric. \_:- symbols & spaces are allowed
properties (optional): Object
Must be a valid JSON object. Max size 16KB & object keys & values cannot exceed 1,000 characters
identity: {
address: string (required)
customerUserId: string (required)
} : either address or customerUserId is required to help us identify a user.
address must be a valid wallet address.
cusomerUserId can be a unique db user id or a unique identifier like email address.
These identifiers are very important part of stitching identities and providing accurate attribution.
|
{% tabs %}
{% tab title="204: No Content OK" %}
{% endtab %}
{% endtabs %}
NodeJs Axios Example
```javascript
const axios = require('axios');
let data = JSON.stringify([
{
"type": "CUSTOM",
"data": {
"name": "ADD_TO_CART",
"properties": {
"optional_data": "here"
}
},
"identity": {
"address": "0x0000000000000000000000000000000000000000",
"customerUserId": "test@gmail.com"
}
},
{
"type": "CUSTOM",
"data": {
"name": "TEST_EVENT_2",
"properties": {
"optional_data": "here"
}
},
"identity": {
"address": "0x0000000000000000000000000000000000000000"
}
}
]);
let config = {
method: 'post',
url: 'https://spindl.link/events/server',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
data : data
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
```
Javascript Fetch Example
```javascript
var myHeaders = new Headers();
myHeaders.append("X-Api-Key", "YOUR_API_KEY");
myHeaders.append("Content-Type", "application/json");
var raw = JSON.stringify([
{
"type": "CUSTOM",
"data": {
"name": "ADD_TO_CART",
"properties": {
"optional_data": "here"
}
},
"identity": {
"address": "0x0000000000000000000000000000000000000000",
"customerUserId": "test@gmail.com"
}
},
{
"type": "CUSTOM",
"data": {
"name": "TEST_EVENT_2",
"properties": {
"optional_data": "here"
}
},
"identity": {
"address": "0x0000000000000000000000000000000000000000",
"customerUserId": "test@gmail.com"
}
}
]);
var requestOptions = {
method: 'POST',
headers: myHeaders,
body: raw,
redirect: 'follow'
};
fetch("https://spindl.link/events/server", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
```
cURL Example
```powershell
curl --location 'https://spindl.link/events/server' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '[
{
"type": "CUSTOM",
"data": {
"name": "ADD_TO_CART",
"properties": {
"optional_data": "here"
}
},
"identity": {
"address": "0x0000000000000000000000000000000000000000",
"customerUserId": "test@gmail.com"
}
},
{
"type": "CUSTOM",
"data": {
"name": "TEST_EVENT_2",
"properties": {
"optional_data": "here"
}
},
"identity": {
"address": "0x0000000000000000000000000000000000000000"
}
}
]'
```
# Data Exports
Spindl data export lets you get a full daily dump of all your client and blockchain events to a shared AWS S3 bucket. The dump is daily, and delayed about 8 hours to allow enough time for proces
Below is the currently supported schema, if you need something specific not listed here please reach out to us!
**Schema**
| Category | Field Name | Description |
| ------------------- | ------------------------- | ------------------------------ |
| Basic Data | event\_id | Unique id of the event |
| | event\_name | |
| | event\_type | |
| | event\_time | |
| | url | |
| | url\_params | |
| | path\_name | |
| Session Info | session\_id | |
| Identity | customer\_user\_id | (If provided in events) |
| | identity\_wallet\_address | |
| Browser Information | device\_user\_agent | User agent of browser |
| | utm\_medium | |
| | utm\_source | |
| | utm\_campaign | |
| | utm\_content | |
| | utm\_term | |
| | referer | Page Referer (from Browser) |
| Onchain Data | chain\_id | |
| | tx\_hash | |
| Attribution Data | attribution\_channel | |
| | attribution\_type | enum (organic, external, etc.) |
**Technical Details**
* **Method 1: Spindl Access to your S3 Bucket**
* You’ll need to give an S3 bucket to the following ARN:
```jsx
arn:aws:iam::475852047645:role/spindl-data-exports-role
```
* For example, a bucket policy might look like:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::475852047645:role/spindl-data-exports-role"
},
"Action": [
"s3:GetObject",
"s3:GetObjectVersion",
"s3:PutObject"
],
"Resource": "arn:aws:s3:::{bucket-name}/*"
},
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::475852047645:role/spindl-data-exports-role"
},
"Action": "s3:GetBucketLocation",
"Resource": "arn:aws:s3:::{bucket-name}"
},
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::475852047645:role/spindl-data-exports-role"
},
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::{bucket-name}",
}
]
}
```
* **Method 2: Spindl IAM Role on your AWS Account**
* Create IAM User on your side with read access to the s3 bucket and provide us the *AWS\_ACCESS\_KEY* and *AWS\_SECRET\_KEY*
File Format and Details
* Format: .csv and .parquet files are currently supported
* Each daily file will be formatted as {YYYY-MM-DD}.csv where the date is the start date
* First file will upload a backfill, and future files will follow the above format
# Android SDK
### Install Using **Android Studio**
1. Open the Project Structure dialog (`File > Project Structure...`).
2. Choose `Dependencies` from the left pane, then the main module (e.g. `app`).
3. Click the `+` button in the `Declared Dependencies` pane, and choose `1 Library Dependency` from the popup menu to open the `Add Library Dependency` dialog.
4. In the `Add Library Dependency` dialog, type `xyz.spindl` under Step 1 and press the `Search` button.
5. Choose the `xyz.spindl` | `sdk` result from the results table, and the highest version available.
6. Make sure `implementation` is selected under Step 2, and press `OK`.
### Initialize SDK
Setup a Spindl instance, e.g. in `MainActivity`:
```kotlin
class MainActivity : ComponentActivity() {
private lateinit var spindl: Spindl
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val apiKey = getString(R.string.spindlApiKey)
lifecycleScope.launch {
spindl = Spindl(context = applicationContext, lifecycleOwner = this@MainActivity)
spindl.initialize(apiKey = apiKey)
}
...
```
### Track Events
Track events with the `track` method:
* `name` is required
* `properties` are optional
```kotlin
val properties = JsonObject()
properties.addProperty("prop1Key", "prop1Value")
spindl.track("eventName", properties)
```
### Identify Users
Once customers enter their customer ID (such as email) and/or wallet information (e.g., after logging in), connect that to the analytics by calling the `identify` method:
```kotlin
spindl.identify(walletAddress = wallet, customerUserId = userId)
```
# iOS (Swift) SDK
### Install Using **Swift Package Manager (requires Xcode 12+)**
1. In Xcode, select File > Swift Packages > Add Package Dependency.
2. Paste the URL [`https://github.com/spindl-xyz/spindl-ios/`](https://github.com/spindl-xyz/spindl-ios/) and a minimum semantic version of v1.0.1. You can see in the [tags sections](https://github.com/spindl-xyz/spindl-ios/tags), our latest releases.
### Initialize SDK
Initialize the SDK with your API key upon launching the app, usually in the `AppDelegate`, or `App` protocol implementor:
```swift
import SpindlSDK
struct MyApp : App {
init() {
Spindl.initialize("")
}
...
}
```
### Track Events
Track events with the `track` method:
* `name` is required
* `properties` are optional
```swift
private func myButtonTappedExample() async throws {
try await Spindl.shared.track(name: "myButtonTapped", properties: ["view":"MyFancyView","otherProperty":"Another one"])
...
}
```
### Identify Users
Once customers enter their customer ID (such as email) and/or wallet information (e.g., after logging in), connect that to the analytics by calling the `identify` method of the `Spindl` singleton:
```swift
private func saveUserIdentityExample(wallet: String?, email: String?) async throws {
try await Spindl.shared.identify(walletAddress: wallet, customerUserId: email)
...
}
```
# On-Chain
To manage incentives and on-chain rewards, Spindl uses smart contracts to pay out rewards.
You can see more technical details here:
{% content-ref url="/pages/jMuiCHHyJ3dQYjlGjTMN" %}
[Technical Details](/spindl/features/referrals/technical-details)
{% endcontent-ref %}
# Rewards
After a successful referral, Spindl will automatically credit wallets with rewards in an on-chain smart contract. The smart contract provides methods to directly to check the status of rewards for a particular wallet and facilitate a withdrawal transaction on-chain.
{% hint style="info" %}
The Smart Contract address and Campaign ID to use in the methods below are specific to your running campaigns, and available within the Spindl Dashboard.
To test, you can use the [0xEC16738B5c89837e90f117dEAb1e9743Be562d69](https://goerli.arbiscan.io/address/0xEC16738B5c89837e90f117dEAb1e9743Be562d69) on Arbitrum Goerli Test Net, with Campaign ID `1`(details [below](#test-contract)).
{% endhint %}
{% hint style="info" %}
All methods below are Smart Contract calls, that can be called via a library like Ethers.js
{% endhint %}
### Check Available Rewards
**RPC Call**
```solidity
getRecipient(_campaignId, _recpientAddress) public view returns (RecipientDetails memory)
```
([Etherscan Reference](https://goerli.arbiscan.io/address/0xEC16738B5c89837e90f117dEAb1e9743Be562d69#readProxyContract#F3))
**Parameters**
* *Campaign ID*: This is the campaign id associated with the campaign you are running. If you are running multiple campaigns, you can check for rewards for each one individually.
* *Recipient Address*: Logged in wallet.
**Response**
```solidity
struct RecipientDetails {
RecipientStatus status;
uint256 earned;
uint256 withdrawn;
}
enum RecipientStatus {
NONE,
ACTIVE,
PAUSED
}
```
(*Note*: The status will almost always be NONE or ACTIVE. The PAUSED status is a special flag that only you can trigger, for suspicious referrers)
**Examples**
Wallet Has Pending Rewards
Recipient 0x0000000000000000000000000000000000000021 has been credited some rewards. The return value is:
```
[1,1200000000,0]
```
The status is ACTIVE (1), which means the recipient is eligible to withdraw funds. They have earned `1200000000` wei, and withdrawn `0` wei, so they are eligible to withdraw `1200000000 - 0 = 1200000000`
Wallet Has No Rewards
Recipient 0x0000000000000000000000000000000000000000 has never been rewarded. The return value is:
`[0, 0, 0`]
The status is NONE (0), which means the recipient address has never been credited. The earned and withdrawn values are 0 (since there is nothing owed to them).
Wallet Has Withdrawn All Rewards
Recipient 0xD4ed4369ae2c27924ee59bd49459C642C20395B2 has withdrawn all rewards. In this case, the return value is:
`[0,1200000000,1200000000]`
The status is ACTIVE (1), which means the recipient is eligible to withdraw funds. They have earned `1200000000` wei, and withdrawn `1200000000` wei, so there are no remaining funds left to withdraw.
### Withdraw Rewards
**Transaction Call**
```solidity
withdrawRecipientEarnings(uint32 _campaignId, uint256 _amount, address _to) public virtual
```
([Etherscan Reference](https://goerli.arbiscan.io/address/0xEC16738B5c89837e90f117dEAb1e9743Be562d69#writeProxyContract#F15))
**Parameters**
* *Campaign ID*: This is the campaign id associated with the campaign you are running.
* *Amount*: The amount to withdraw. This is usually the total withdrawal amount, but can be a smaller amount as well. This will be in the currency for the campaign.
* *To*: The recipient of the funds. This is usually the address of the wallet calling this function, but you can set it to another address specific by the user
**Returns**
This is a transaction, so there will be no return type. The transaction should be successful if the caller is owed at least that amount in the campaign.
### Campaign Details
**RPC Call**
```solidity
campaigns(_campaignId) public view returns (totalBudget uint256, status uint8, paymentType address, totalEarned uint256)
```
([Etherscan Reference](https://goerli.arbiscan.io/address/0xEC16738B5c89837e90f117dEAb1e9743Be562d69#readProxyContract#F2))
#### Parameters
* *Campaign ID*: This is the campaign id associated with the campaign you are running.
**Returns**
* Total Budget: The total budget set by the owner of the campaign
* Status
* Payment Type: The ERC20 token, or 0x0... for the native currency
* Total Earned: The total amount of token allocated referrers and referees.
### Test Contract
Here is an example contract on the Arbitrum Tesnet:
* Address: 0xEC16738B5c89837e90f117dEAb1e9743Be562d69 ([URL](https://goerli.arbiscan.io/address/0xEC16738B5c89837e90f117dEAb1e9743Be562d69#readProxyContract))
* Campaign ID: 1
We populated the campaign with earnings for these referrer addresses to make testing easier:
```typescript
0xD4ed4369ae2c27924ee59bd49459C642C20395B2
0x0000000000000000000000000000000000000021
0x0000000000000000000000000000000000000022
0x0000000000000000000000000000000000000023
0x0000000000000000000000000000000000000024
0x0000000000000000000000000000000000000025
0x0000000000000000000000000000000000000026
0x0000000000000000000000000000000000000027
0x0000000000000000000000000000000000000028
0x0000000000000000000000000000000000000029
0x0000000000000000000000000000000000000030
```
### Contract ABI
You can use this to interact with the contract with any Web3 client libraries, like Ethers.js
```
[{"inputs":[],"stateMutability":"nonpayable","type":"constructor"},{"inputs":[],"name":"BadAddress","type":"error"},{"inputs":[],"name":"BadPayment","type":"error"},{"inputs":[],"name":"BadRequest","type":"error"},{"inputs":[],"name":"ImproperCampaignState","type":"error"},{"inputs":[],"name":"IncorrectAmount","type":"error"},{"inputs":[],"name":"OverAttributed","type":"error"},{"inputs":[],"name":"PaymentTypeDoesNotExist","type":"error"},{"inputs":[],"name":"Unauthorized","type":"error"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"uint32","name":"campaignId","type":"uint32"},{"indexed":false,"internalType":"uint256","name":"withdrawAmount","type":"uint256"},{"indexed":false,"internalType":"uint256","name":"newTotalBalance","type":"uint256"}],"name":"BalanceWithdrawn","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"uint32","name":"campaignId","type":"uint32"},{"indexed":false,"internalType":"address","name":"paymentType","type":"address"}],"name":"CampaignCreated","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"uint32","name":"campaignId","type":"uint32"},{"indexed":false,"internalType":"uint256","name":"updatedBudget","type":"uint256"}],"name":"CampaignFunded","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"uint32","name":"campaignId","type":"uint32"},{"indexed":false,"internalType":"enum PayoutVault.CampaignStatus","name":"oldState","type":"uint8"},{"indexed":false,"internalType":"enum PayoutVault.CampaignStatus","name":"newState","type":"uint8"}],"name":"CampaignStatusUpdated","type":"event"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"uint8","name":"version","type":"uint8"}],"name":"Initialized","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"address","name":"oldAddress","type":"address"},{"indexed":false,"internalType":"address","name":"newAddress","type":"address"}],"name":"ManagerAddressUpdated","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"address","name":"previousOwner","type":"address"},{"indexed":true,"internalType":"address","name":"newOwner","type":"address"}],"name":"OwnershipTransferred","type":"event"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"address","name":"paymentAddress","type":"address"}],"name":"PaymentAdded","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"uint32","name":"campaignId","type":"uint32"},{"indexed":false,"internalType":"address","name":"recipientAddress","type":"address"}],"name":"RecipientAdded","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"uint32","name":"campaignId","type":"uint32"},{"indexed":true,"internalType":"address","name":"addr","type":"address"},{"indexed":false,"internalType":"enum PayoutVault.RecipientStatus","name":"status","type":"uint8"}],"name":"RecipientStatusUpdated","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"uint32","name":"campaignId","type":"uint32"},{"indexed":true,"internalType":"address","name":"recipientAddress","type":"address"},{"indexed":false,"internalType":"address","name":"paymentType","type":"address"},{"indexed":false,"internalType":"uint256","name":"newEarnings","type":"uint256"}],"name":"UpdateCompleted","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"uint32","name":"campaignId","type":"uint32"},{"indexed":true,"internalType":"address","name":"recipientAddress","type":"address"},{"indexed":false,"internalType":"address","name":"paymentType","type":"address"},{"indexed":false,"internalType":"uint256","name":"totalWithdrawn","type":"uint256"},{"indexed":false,"internalType":"enum PayoutVault.RecipientWithdrawType","name":"withdrawType","type":"uint8"}],"name":"WithdrawSuccess","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"address","name":"oldAddress","type":"address"},{"indexed":false,"internalType":"address","name":"newAddress","type":"address"}],"name":"WorkerAddressUpdated","type":"event"},{"inputs":[{"internalType":"address","name":"_address","type":"address"}],"name":"addERC20Payment","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"uint32","name":"_campaignId","type":"uint32"},{"internalType":"address[]","name":"_recipientAddresses","type":"address[]"}],"name":"addRecipients","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"campaignCounter","outputs":[{"internalType":"uint32","name":"","type":"uint32"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint32","name":"","type":"uint32"}],"name":"campaigns","outputs":[{"internalType":"uint256","name":"totalBudget","type":"uint256"},{"internalType":"enum PayoutVault.CampaignStatus","name":"status","type":"uint8"},{"internalType":"address","name":"paymentType","type":"address"},{"internalType":"uint256","name":"totalEarned","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_paymentType","type":"address"},{"internalType":"address[]","name":"_recipientAddresses","type":"address[]"}],"name":"createCampaign","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"uint32","name":"_campaignId","type":"uint32"},{"internalType":"uint256","name":"_amount","type":"uint256"}],"name":"fundCampaign","outputs":[],"stateMutability":"payable","type":"function"},{"inputs":[{"internalType":"uint32","name":"_campaignId","type":"uint32"},{"internalType":"address","name":"_recipientAddress","type":"address"}],"name":"getRecipient","outputs":[{"components":[{"internalType":"enum PayoutVault.RecipientStatus","name":"status","type":"uint8"},{"internalType":"uint256","name":"earned","type":"uint256"},{"internalType":"uint256","name":"withdrawn","type":"uint256"}],"internalType":"struct PayoutVault.RecipientDetails","name":"","type":"tuple"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_owner","type":"address"},{"internalType":"address","name":"_managerAddress","type":"address"},{"internalType":"address","name":"_workerAddress","type":"address"},{"internalType":"address[]","name":"_paymentTypes","type":"address[]"}],"name":"initialize","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"managerAddress","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"owner","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"","type":"address"}],"name":"paymentTypes","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint32","name":"_campaignId","type":"uint32"},{"internalType":"address[]","name":"_recipientAddresses","type":"address[]"}],"name":"pushRecipientEarnings","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"renounceOwnership","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"uint32","name":"_campaignId","type":"uint32"},{"internalType":"enum PayoutVault.CampaignStatus","name":"_status","type":"uint8"}],"name":"setCampaignStatus","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_newAddress","type":"address"}],"name":"setManagerAddress","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"uint32","name":"_campaignId","type":"uint32"},{"internalType":"address","name":"_recipientAddress","type":"address"},{"internalType":"enum PayoutVault.RecipientStatus","name":"_status","type":"uint8"}],"name":"setRecipientStatus","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_newAddress","type":"address"}],"name":"setWorkerAddress","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"newOwner","type":"address"}],"name":"transferOwnership","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"bytes","name":"performData","type":"bytes"}],"name":"updateBalances","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"components":[{"internalType":"uint32","name":"campaignId","type":"uint32"},{"internalType":"uint256","name":"amount","type":"uint256"}],"internalType":"struct PayoutVault.RecipientEarnings[]","name":"_campaigns","type":"tuple[]"},{"internalType":"address","name":"_to","type":"address"}],"name":"withdrawManyRecipientEarnings","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"uint32","name":"_campaignId","type":"uint32"},{"internalType":"uint256","name":"_amount","type":"uint256"},{"internalType":"address","name":"_to","type":"address"}],"name":"withdrawRecipientEarnings","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"uint32","name":"_campaignId","type":"uint32"},{"internalType":"address","name":"_to","type":"address"}],"name":"withdrawRemainingCampaignBalance","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"workerAddress","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"}]
```
# Contact Spindl
Email us at contact\@spindl.xyz
# 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
```
{% 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
```
{% endtab %}
{% endtabs %}