Skip to main content

​
Initialization

✅ DO:
  • Initialize once per session, on app load
  • await the init() result before fetching ads
  • Handle initialization errors before proceeding
  • Store the sdk instance at module/app level
❌ DON’T:
  • Create multiple VelocitySDK instances
  • Call init() inside render loops or ad-fetch functions
  • Ignore initialization errors
// ✅ Good — single instance, initialized once
const sdk = new VelocitySDK({ publisherKey: 'YOUR_PUBLISHER_KEY' });
await sdk.init({ publisherUserId: 'user-123' });

// ❌ Bad — multiple instances
const sdk1 = new VelocitySDK({ publisherKey: 'YOUR_PUBLISHER_KEY' });
const sdk2 = new VelocitySDK({ publisherKey: 'YOUR_PUBLISHER_KEY' });

​
Ad Fetching

✅ DO:
  • Provide meaningful prompt and aiResponse values
  • Always check ads.length before rendering
  • Specify accurate dimensions matching your ad container
❌ DON’T:
  • Use empty or placeholder prompts
  • Block UI during ad loading — fetch asynchronously
  • Hardcode dimensions that don’t match your layout
// ✅ Good — descriptive context, accurate dimensions
const adsResult = await sdk.fetchAd({
  prompt: 'What are the best running shoes for marathons?',
  aiResponse: 'For marathons, cushioning and support are key...',
  dimensions: {
    width: adContainer.offsetWidth,
    height: adContainer.offsetHeight
  }
});

// ❌ Bad — empty prompt, arbitrary dimensions
const adsResult = await sdk.fetchAd({
  prompt: '',
  aiResponse: '',
  dimensions: { width: 0, height: 0 }
});

​
Error Handling

Always handle both init and fetch errors to avoid silent failures: 
// ✅ Correct — handle errors at every step
const initResult = await sdk.init({ publisherUserId: 'user-123' });
if (!initResult.success) {
  console.error('Init failed:', initResult.error.message);
  return;
}

const adsResult = await sdk.fetchAd({ ... });
if (adsResult.success && adsResult.data.ads.length > 0) {
  renderAd(adsResult.data.ads[0]);
} else {
  showFallbackContent();
}

// ❌ Wrong — no error handling
await sdk.init({ publisherUserId: 'user-123' });
const adsResult = await sdk.fetchAd({ ... });
renderAd(adsResult.data.ads[0]);  // Will throw if no ads or init failed

​
Ad Rendering

✅ DO:
  • Use clickUrl to make the full ad clickable
  • Open ad links in a new tab with rel="noopener noreferrer"
  • Display the top ad (ads[0]) — ads are sorted by bid price
❌ DON’T:
  • Ignore clickUrl — this is required for monetization
  • Render ads in iframes or sandboxed environments that block navigation
// ✅ Good — proper click handling
const adLink = document.createElement('a');
adLink.href = ad.adPayload.clickUrl;
adLink.target = '_blank';
adLink.rel = 'noopener noreferrer';

​
Configuration

Use timeout and retries to handle slow networks gracefully: 
const sdk = new VelocitySDK({
  publisherKey: 'YOUR_PUBLISHER_KEY',
  timeout: 8000,   // 8 seconds
  retries: 2       // 2 retries (3 attempts total, max)
});
Use a custom logger in development to capture SDK activity: 
const sdk = new VelocitySDK({
  publisherKey: 'YOUR_PUBLISHER_KEY',
  logger: {
    log: msg => console.log('[Velocity]', msg),
    error: msg => console.error('[Velocity]', msg),
    warn: msg => console.warn('[Velocity]', msg)
  }
});