Getting Started with Cogniad

This guide will walk you through setting up your Cogniad account, creating your first campaign, and serving ads. You'll be up and running in minutes.

Prerequisites

Before you begin, make sure you have:

A Cogniad account (sign up at cogniad.com)
API credentials (API key and secret)
Basic understanding of REST APIs
Access to your website or application where you'll serve ads

Step 1: Create Your Account

If you haven't already, create your Cogniad account. You can sign up as either a publisher (to monetize your inventory) or an advertiser (to run campaigns).

Visit the Cogniad homepage
Click "Start Free Trial"
Choose your account type (Publisher or Advertiser)
Complete the registration form
Verify your email address

Step 2: Get Your API Credentials

After logging in, navigate to your account settings to retrieve your API credentials:

Go to Settings → API Keys
Click Generate New API Key
Copy your API Key and API Secret
Store them securely - you'll need them for all API requests

Keep Your Credentials Secure

Never commit API keys to version control. Use environment variables or secure secret management systems to store your credentials.

Step 3: Set Up Authentication

All API requests require authentication using your API credentials. Cogniad uses JWT (JSON Web Tokens) for authentication.

Using cURL

bash

curl -X POST https://api.cogniad.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key",
    "api_secret": "your_api_secret"
  }'

Using JavaScript

javascript

const response = await fetch('https://api.cogniad.com/v1/auth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    api_key: 'your_api_key',
    api_secret: 'your_api_secret'
  })
});

const { access_token } = await response.json();

// Use the token in subsequent requests
const headers = {
  'Authorization': `Bearer ${access_token}`,
  'Content-Type': 'application/json'
};

Using Python

python

import requests

response = requests.post(
    'https://api.cogniad.com/v1/auth/token',
    json={
        'api_key': 'your_api_key',
        'api_secret': 'your_api_secret'
    }
)

data = response.json()
access_token = data['access_token']

# Use the token in subsequent requests
headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}

Step 4: Create Your First Campaign

Now that you're authenticated, let's create your first campaign. A campaign is a container for your ads with specific targeting, budget, and scheduling.

For Advertisers

javascript

const campaign = await fetch('https://api.cogniad.com/v1/campaigns', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'My First Campaign',
    advertiser_id: 'your_advertiser_id',
    start_date: '2024-01-01',
    end_date: '2024-12-31',
    daily_impression_limit: 100000,
    priority: 5,
    status: 'active'
  })
});

const campaignData = await campaign.json();
console.log('Campaign created:', campaignData);

For Publishers

As a publisher, you'll first need to create a zone (ad placement location) on your website:

javascript

const zone = await fetch('https://api.cogniad.com/v1/zones', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Homepage Banner',
    publisher_id: 'your_publisher_id',
    type: 'banner',
    width: 728,
    height: 90,
    status: 'active'
  })
});

const zoneData = await zone.json();
console.log('Zone created:', zoneData);

Step 5: Create a Banner

Banners are the actual ad creatives that will be displayed. You can create image banners, HTML banners, or text banners.

javascript

const formData = new FormData();
formData.append('campaign_id', campaignData.id);
formData.append('name', 'My First Banner');
formData.append('type', 'image');
formData.append('width', '728');
formData.append('height', '90');
formData.append('file', bannerImageFile); // Your image file
formData.append('click_url', 'https://example.com');

const banner = await fetch('https://api.cogniad.com/v1/banners', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`
  },
  body: formData
});

const bannerData = await banner.json();
console.log('Banner created:', bannerData);

Step 6: Serve Your First Ad

Now that you have a campaign and banner set up, you can serve ads. For publishers, use the zone invocation code. For advertisers, ads will be automatically served based on campaign targeting.

Zone Invocation Code

After creating a zone, you'll receive an invocation code. Add this to your HTML:

html

<!-- Zone Invocation Code -->
<div id="cogniad-zone-12345"></div>
<script>
  (function() {
    var script = document.createElement('script');
    script.src = 'https://cdn.cogniad.com/v1/delivery/zone/12345.js';
    script.async = true;
    document.head.appendChild(script);
  })();
</script>

Direct API Call

You can also request ads directly via the API:

javascript

const adRequest = await fetch('https://api.cogniad.com/v1/delivery/ad', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    zone_id: '12345',
    width: 728,
    height: 90,
    user_id: 'user_123', // Optional: for frequency capping
    url: window.location.href
  })
});

const ad = await adRequest.json();
// Render the ad using ad.html or ad.url

Step 7: Use SDKs (Optional)

Cogniad provides SDKs for popular programming languages to simplify integration:

JavaScript SDK

bash

npm install @cogniad/sdk

javascript

import { CogniadSDK } from '@cogniad/sdk';

const sdk = new CogniadSDK({
  apiKey: 'your_api_key',
  apiSecret: 'your_api_secret'
});

// Request an ad
const ad = await sdk.delivery.request({
  zoneId: '12345',
  width: 728,
  height: 90
});

// Render the ad
sdk.delivery.render(ad, document.getElementById('ad-container'));

Python SDK

bash

pip install cogniad-sdk

python

from cogniad import CogniadSDK

sdk = CogniadSDK(
    api_key='your_api_key',
    api_secret='your_api_secret'
)

# Request an ad
ad = sdk.delivery.request(
    zone_id='12345',
    width=728,
    height=90
)

# Use ad.html or ad.url to render

Next Steps

Now that you've completed the basics, explore these topics:

Advertiser Guide - Learn about campaign management and targeting
Publisher Guide - Optimize your inventory and monetization
Tracking - Implement impression, click, and conversion tracking
Reporting - Access statistics and analytics
API Reference - Complete API documentation

Need Help?

If you run into any issues, check out our Glossary for definitions, or contact our support team for assistance.