Skip to main content
SDK v7.x · Last verified March 2026 · iOS · Android · Web · Flutter
// 1. Fetch network ads
const { data: ads } = await AdRepository.getNetworkAds({ placement: 'feed' });

// 2. Track an impression
await AdRepository.markAdSeen(ads[0].adId);

// 3. Track a click
await AdRepository.markAdClicked(ads[0].adId);
Full walkthrough below ↓
Platform note — code samples below use TypeScript. Every method has an equivalent in the iOS (Swift), Android (Kotlin), and Flutter (Dart) SDKs — see the linked SDK reference in each step.
Native ads blend into your social feed, generating revenue without disrupting the user experience. social.plus provides a console-driven ad system — configure ad placements and creatives in the Admin Console, then fetch and render them in your app using the SDK. This guide covers fetching ads, tracking impressions and clicks, and placing ads within feeds.
Prerequisites: SDK installed and authenticated → SDK Setup. Ads must be configured in Admin Console → Settings → Premium Ads with at least one active creative uploaded.Also recommended: Complete Build a Social Feed first — ads render inline within feed content.
After completing this guide you’ll have:
  • Native ad units rendering in the feed at configured intervals
  • Impression and click events tracked and sent to the Admin Console
  • Ad frequency and targeting rules configured via the Admin Console

​
Quick Start: Fetch and Display Ads

TypeScript
import { AdRepository } from '@amityco/ts-sdk';

try {
  const { ads, settings } = await AdRepository.getNetworkAds();
  // ads: Array of Ad objects with creative URLs, CTAs, and metadata
  // settings: placement configuration (frequency, positions)
} catch (error) {
  console.error('Failed to fetch ads:', error);
}
Full reference → Ads

​
Step-by-Step Implementation

1

Fetch ads and placement settings

Call getNetworkAds() on app launch and cache the result. The response includes the ad creatives (images, text, CTAs) and settings that define where and how often to show them.
TypeScript
import { AdRepository } from '@amityco/ts-sdk';

const { ads, settings } = await AdRepository.getNetworkAds();
console.log(`${ads.length} ads available`);
console.log('Placement frequency:', settings.frequency);
Full reference → Ads
2

Insert ads into the feed

Use the placement settings to insert ad cards at the right intervals in your social feed. A common pattern is to insert an ad every N posts.
TypeScript
const buildFeedWithAds = (posts: any[], ads: Amity.Ad[], frequency: number) => {
  const feedItems: any[] = [];
  let adIndex = 0;

  posts.forEach((post, i) => {
    feedItems.push({ type: 'post', data: post });

    // Insert ad every `frequency` posts
    if ((i + 1) % frequency === 0 && adIndex < ads.length) {
      feedItems.push({ type: 'ad', data: ads[adIndex] });
      adIndex++;
    }
  });

  return feedItems;
};
3

Track impressions

When an ad enters the viewport, mark it as seen. This records an impression for analytics. Use an Intersection Observer (web) or equivalent visibility detection on mobile.
TypeScript
// When ad card becomes visible in the viewport
ad.analytics.markAsSeen(Amity.AdPlacement.FEED);
Full reference → Ads
4

Track link clicks

When a user taps an ad’s call-to-action, record the click before opening the destination URL.
TypeScript
const handleAdClick = (ad: Amity.Ad) => {
  // Record the click
  ad.analytics.markLinkAsClicked(Amity.AdPlacement.FEED);

  // Open the destination
  window.open(ad.callToActionUrl, '_blank');
};
Full reference → Ads
5

Configure ads in the Admin Console

Set up ad creatives, targeting, and placement rules in Admin Console → Settings → Premium Ads:
  • Creative: Upload ad image/video, set headline text and CTA button text
  • Targeting: Choose which communities or content categories to show the ad in
  • Frequency: How often ads appear in the feed (every N posts)
  • Schedule: Start/end dates for the campaign
→ Admin Console: Premium Ads

​
Connect to Moderation & Analytics

View impression counts, click-through rates, and conversion metrics per ad creative in Admin Console → Analytics → Ads Performance. Use this to optimize creative and placement.
Community moderators can flag ads that don’t fit their community’s tone. Flagged ads are reviewed in the Admin Console moderation queue.
Receive ad impression and click events via webhooks to sync with your ad server or analytics pipeline.→ Webhook Events

​
Common Mistakes

Rendering ads without tracking impressions — If you display an ad but don’t call markAdSeen(), the impression isn’t counted and revenue isn’t attributed. Always track when the ad enters the viewport.
// ❌ Bad — ad shown but no tracking
return <AdBanner ad={ad} />;

// ✅ Good — track on visibility
const onVisible = () => AdRepository.markAdSeen(ad.adId);
return <AdBanner ad={ad} onVisible={onVisible} />;
Caching ads for too long — Ad creatives and targeting change frequently. Fetch fresh ads on each feed load instead of caching them across sessions.
Placing ads too frequently in the feed — Ads every 3–4 posts degrade user experience. A ratio of 1 ad per 8–10 organic posts maintains engagement while generating revenue.

​
Best Practices

  • Don’t show ads in the first 3 positions of the feed — let users see content first
  • Match the ad card styling to your post card styling for a native feel
  • Label ads clearly with an “Ad” or “Sponsored” tag — transparency builds trust
  • Don’t show more than 1 ad per 5 posts — higher density drives users away
  • Hide ads from the feed when ad count is 0 — never show a broken ad placeholder
  • Only call markAsSeen() when the ad is at least 50% visible for 1+ seconds — this matches industry standards
  • Don’t track impressions when the app is backgrounded or the screen is off
  • De-duplicate impressions client-side — only track the first impression per ad per session
  • Use Amity.AdPlacement.FEED for in-feed ads and the appropriate placement enum for other positions
  • Cache getNetworkAds() for the session — ads change infrequently
  • Pre-load ad images while the user is scrolling through content
  • Lazy-load ad video creatives — only start playback when the ad is in view
  • Keep ad card rendering lightweight — heavy ad views slow down feed scrolling
Dive deeper: Posts API Reference has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

​
Next Steps

Your next step → Post Impressions & Creator Analytics

Ads are running — now track organic content performance alongside ad metrics.
Or explore related guides:

Build a Social Feed

Build the feed where ads are placed

Stories & Ephemeral Content

Integrate sponsored stories alongside user stories

Content Moderation Pipeline

Handle flagged ad content