StageUp
Mobile SDKPromotion

Flutter Promotion

A guide to managing promotions with the NBase AdStage SDK in a Flutter application.

1. Overview

  • Query and display promotions (banner/popup/native), and track impressions/clicks.
  • Filter by banner type, audience, and display limits to show only relevant promotions.

2. Quick start

2.1 Install SDK

# pubspec.yaml
dependencies:
  nbase_ad_flutter_sdk: ^1.0.1
flutter pub get

2.2 Basic setup

Android setup

android/app/src/main/kotlin/.../MainActivity.kt:

import android.os.Bundle
import io.flutter.embedding.android.FlutterActivity
import io.nbase.adapter.adstage.AdStageSDK
 
class MainActivity : FlutterActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
 
        // Set API key
        AdStageSDK.setApiKey("YOUR_API_KEY")
    }
}

iOS setup

iOS requires no additional native changes beyond Flutter-side SDK initialization.

3. Flutter implementation

3.1 Initialize SDK

import 'package:flutter/material.dart';
import 'package:nbase_ad_flutter_sdk/nbase_ad_flutter_sdk.dart';
 
class MyApp extends StatefulWidget {
  @override
  State<MyApp> createState() => _MyAppState();
}
 
class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    _initializeSDK();
  }
 
  Future<void> _initializeSDK() async {
    try {
      await NbaseAdFlutterSdk.initializeAdStageSDK({
        'apiKey': 'YOUR_API_KEY',
      });
    } catch (e) {
      debugPrint('Failed to initialize SDK: $e');
    }
  }
 
  @override
  Widget build(BuildContext context) {
    return MaterialApp(home: Scaffold(body: Container()));
  }
}

4. Promotion features

4.1 Open a promotion

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

Future<void> showPromotion(BuildContext context) async {
  try {
    final result = await NbaseAdFlutterSdk.openPromotion(
      bannerType: 'NATIVE',        // Banner type (BANNER | POPUP | NATIVE, etc.)
      targetAudience: 'new_user',  // Target audience (optional)
      showTodayButton: true,       // Show "Do not show again today" button (optional)
    );
 
    if (result.success && result.url.isNotEmpty) {
      debugPrint('Promotion URL: ${result.url}');
 
      // Open promotion page via WebView or browser
      await _openPromotionPage(context, result.url);
    } else {
      debugPrint('No promotion to display.');
    }
  } catch (e) {
    debugPrint('Failed to open promotion: $e');
  }
}
 
Future<void> _openPromotionPage(BuildContext context, String url) async {
  // Example: navigate to a WebView screen using webview_flutter
  Navigator.push(
    context,
    MaterialPageRoute(
      builder: (context) => PromotionWebView(url: url),
    ),
  );
}

4.2 Get promotion list

Fetch available promotions and show them in a list/carousel.

List<Map<String, dynamic>> _promotions = [];
 
Future<void> loadPromotionList() async {
  try {
    final result = await NbaseAdFlutterSdk.getPromotionList(
      bannerType: 'BANNER',  // Filter by banner type
      limit: 10,             // Max count
    );
 
    debugPrint('Found ${result.promotions.length} promotions');
 
    for (final promotion in result.promotions) {
      debugPrint('Promotion ID: ${promotion['id']}');
      debugPrint('Title: ${promotion['title']}');
      debugPrint('Description: ${promotion['description']}');
      debugPrint('Image URL: ${promotion['imageUrl']}');
      debugPrint('Link URL: ${promotion['linkUrl']}');
      debugPrint('Start: ${promotion['startDate']}');
      debugPrint('End: ${promotion['endDate']}');
      debugPrint('---');
    }
 
    // Bind to UI
    _promotions = List<Map<String, dynamic>>.from(result.promotions);
  } catch (e) {
    debugPrint('Failed to load promotion list: $e');
  }
}

5. Advanced

5.1 Use various banner types

// Open a popup promotion
Future<void> showPopupPromotion() async {
  final result = await NbaseAdFlutterSdk.openPromotion(
    bannerType: 'POPUP',
    targetAudience: 'all',
    showTodayButton: true,
  );
  if (result.success && result.url.isNotEmpty) {
    debugPrint('Popup promotion URL: ${result.url}');
  }
}
 
// Banner promotion list
Future<void> getBannerPromotions() async {
  final result = await NbaseAdFlutterSdk.getPromotionList(
    bannerType: 'BANNER',
    limit: 5,
  );
  debugPrint('Banner promotions: ${result.promotions.length}');
}
 
// Native promotion list
Future<void> getNativePromotions() async {
  final result = await NbaseAdFlutterSdk.getPromotionList(
    bannerType: 'NATIVE',
    limit: 10,
  );
  debugPrint('Native promotions: ${result.promotions.length}');
}

6. Troubleshooting

  • Promotion not displayed: verify API key, SDK initialization, and network connectivity.
  • Android build errors: run flutter clean && flutter pub get, check Manifest/dependencies.
  • iOS build errors: run cd ios && pod install, verify permissions/config.

Note: Supported versions (example) — Flutter 3.10.0+, iOS 12.0+, Android API 21+

Table of Contents