Skip to main content

​
Initialization

✅ DO:
  • Initialize in main() before runApp()
  • Use async/await properly
  • Handle initialization errors
  • Check initialization status before loading ads
❌ DON’T:
  • Initialize multiple times
  • Initialize in widget build() methods
  • Ignore initialization errors
  • Load ads before initialization completes

​
Ad Loading

✅ DO:
  • Provide meaningful context (user query, AI response)
  • Use conversation history for better targeting
  • Handle errors gracefully with try/catch
  • Call destroy() when ads are no longer needed
  • Use VelocityNativeAdViewRequest when you want SDK-rendered views
❌ DON’T:
  • Use empty or placeholder prompts
  • Block UI during ad loading
  • Forget to call destroy() on ad instances
  • Create ad instances in build() methods

​
Error Handling

// ✅ Correct — always handle errors
final ad = VelocityNativeAd(request);
try {
  await ad.load();
  // Display ad
} catch (e) {
  print('Error: $e');
  // Show fallback content or hide ad space
}

// ❌ Wrong — don't ignore errors
final ad = VelocityNativeAd(request);
await ad.load(); // Unhandled exception if load fails

​
Ad Lifecycle

✅ DO:
  • Create VelocityNativeAd instances in initState() or event handlers
  • Store ad references in state
  • Call destroy() in dispose() for all loaded ads
  • Track all loaded ads for proper cleanup
❌ DON’T:
  • Create ad instances in build() methods
  • Forget to destroy ads when navigating away
  • Hold references to destroyed ads

​
Multiple Ads

// ✅ Correct — track and clean up all instances
final ads = <VelocityNativeAd>[];

Future<void> loadAd() async {
  final ad = VelocityNativeAd(request);
  await ad.load();
  ads.add(ad);
}

@override
void dispose() {
  for (final ad in ads) {
    ad.destroy();
  }
  super.dispose();
}