Skip to main content

​
“SDK not initialized” Error

Problem: Loading an ad before initialize() has been called or completed. Solution: 
import 'dart:io';

Future<void> loadAd() async {
  final isInitialized = await VelocityAds.isInitialized();
  if (!isInitialized) {
    const iosAppKey = 'your-ios-app-key';
    const androidAppKey = 'your-android-app-key';
    final appKey = Platform.isIOS ? iosAppKey : androidAppKey;
    await VelocityAds.initialize(appKey: appKey);
  }

  final ad = VelocityNativeAd(VelocityNativeAdRequest(prompt: 'your prompt'));
  await ad.load();
}

​
Ads Not Loading

Checklist:
  • ✅ SDK initialized in main() before runApp()
  • ✅ Network connectivity available
  • ✅ App key is correct for the current platform (iOS key on iOS, Android key on Android)
  • ✅ Check error messages in callbacks
Enable Debug Mode: 
import 'dart:io';

const iosAppKey = 'your-ios-app-key';
const androidAppKey = 'your-android-app-key';
final appKey = Platform.isIOS ? iosAppKey : androidAppKey;

await VelocityAds.initialize(
  appKey: appKey,
  debug: true,  // Enable debug logs
);

​
Ad Load Errors via Listener

Problem: Platform-specific errors from the native layer during ad load. Solution: Use the onAdFailedToLoad callback: 
class MyAdListener extends VelocityNativeAdListener {
  @override
  void onAdFailedToLoad(VelocityNativeAd ad, VelocityAdsError error) {
    print('Ad load error [${error.code}]: ${error.message}');
    // Show fallback content
  }
}
For initialization failures, catch VelocityAdsError from initialize(): 
try {
  await VelocityAds.initialize(appKey: appKey);
} on VelocityAdsError catch (e) {
  print('Init error [${e.code}]: ${e.message}');
}

​
Build Errors with Obfuscation

Problem: Release builds fail or crash due to obfuscation. Solution: Use the correct obfuscation flags: 
# Android APK
flutter build apk --obfuscate --split-debug-info=build/symbols

# App Bundle (recommended for Play Store)
flutter build appbundle --obfuscate --split-debug-info=build/symbols

​
iOS Build Cannot Resolve Package Dependencies

CocoaPods: 
pod repo update
pod install
Swift Package Manager: Ensure SPM is enabled in Flutter: 
flutter config --enable-swift-package-manager
Then re-run dependency resolution: 
flutter pub get

​
No Ads Returned

Possible causes:
  • No ads available for the given context
  • Network issues
  • Invalid app key for the current platform
  • Ad unit not configured
Solution: Check logs with debug mode enabled. The SDK will continue to function even if no ads are available.