React Native Promotion

This guide describes how to manage promotions in a React Native application using the NBase AdStage SDK.

1. Overview

Promotions display and track marketing campaigns, banners, and popups within your app.
The AdStage SDK supports querying, opening (displaying), and tracking promotions.

2. Quick start

npm install nbase-ad-react-native-sdk
# or
yarn add nbase-ad-react-native-sdk
 
# For iOS
cd ios && pod install

3. Promotion features

3.1 Open a promotion

Open a promotion that matches specific conditions and display it to the user.

import { AdStageSDK } from 'nbase-ad-react-native-sdk';
import { Linking } from 'react-native';
 
const showPromotion = async () => {
  try {
    const result = await AdStageSDK.openPromotion({
      bannerType: 'NATIVE',           // Banner type: NATIVE, POPUP, BANNER
      targetAudience: 'new_user',     // Target audience
      showTodayButton: true,          // Show "Do not show again today" button
    });
 
    if (result.success && result.url) {
      console.log('Promotion URL:', result.url);
      // Open promotion page in external browser
      await Linking.openURL(result.url);
 
      // Optional: track open event
      AdStageSDK.trackEvent('promotion_opened', {
        url: result.url,
        promotionId: result.promotionId,
        timestamp: new Date().toISOString(),
      });
    } else {
      console.log('No promotion to display.');
    }
  } catch (error) {
    console.error('Failed to open promotion:', error);
  }
};
 
// Open with different banner types
const showPopupPromotion = async () => {
  const result = await AdStageSDK.openPromotion({
    bannerType: 'POPUP',
    targetAudience: 'all',
    showTodayButton: true,
  });
  if (result.success && result.url) {
    await Linking.openURL(result.url);
  }
};
 
const showBannerPromotion = async () => {
  const result = await AdStageSDK.openPromotion({
    bannerType: 'BANNER',
    targetAudience: 'returning_user',
    showTodayButton: false,
  });
  if (result.success && result.url) {
    await Linking.openURL(result.url);
  }
};

3.2 Get promotion list

Fetch available promotions and render them in your app.

import { AdStageSDK } from 'nbase-ad-react-native-sdk';
 
const loadPromotionList = async () => {
  try {
    const result = await AdStageSDK.getPromotionList({
      bannerType: 'BANNER',    // Filter by banner type
      limit: 10,               // Max count
    });
 
    console.log(`Found ${result.promotions.length} promotions`);
 
    result.promotions.forEach((promotion, index) => {
      console.log(`Promotion ${index + 1}:`);
      console.log(`   ID: ${promotion.id}`);
      console.log(`   Title: ${promotion.title}`);
      console.log(`   Description: ${promotion.description}`);
      console.log(`   Image URL: ${promotion.imageUrl}`);
      console.log(`   Link URL: ${promotion.linkUrl}`);
      console.log(`   Start: ${promotion.startDate}`);
      console.log(`   End: ${promotion.endDate}`);
      console.log('---');
    });
 
    return result.promotions;
  } catch (error) {
    console.error('Failed to load promotions:', error);
    return [];
  }
};
 
// Examples by banner type
const loadBannerPromotions = async () => {
  return await AdStageSDK.getPromotionList({
    bannerType: 'BANNER',
    limit: 5,
  });
};
 
const loadPopupPromotions = async () => {
  return await AdStageSDK.getPromotionList({
    bannerType: 'POPUP',
    limit: 3,
  });
};
 
const loadNativePromotions = async () => {
  return await AdStageSDK.getPromotionList({
    bannerType: 'NATIVE',
    limit: 10,
  });
};

4. Troubleshooting

Promotion not displayed

Ensure native initialization (e.g., AdStageInitializer.load()) is completed
Check network connectivity
Verify promotions meeting the conditions are registered on the server

Promotion list returns an empty array

Verify bannerType and targetAudience
Check server registration and API response logs

Images not loading

Ensure image URLs use HTTPS
Android: verify network security config
iOS: verify ATS (App Transport Security) settings

WebView/browser does not open

Check Linking.canOpenURL() first
Validate URL format and that a browser app exists on the device

Build errors

Re-run npm install && cd ios && pod install
Clear React Native cache: npx react-native start --reset-cache
Android clean build: cd android && ./gradlew clean