API Reference

​

VelocityAds

​

initialize()

Future<Map<String, dynamic>> initialize({
  required String appKey,
  bool debug = false,
})

• appKey - Your application key for the current platform (required). iOS and Android use different keys.
• debug - Enable debug logging (default: false)

​

setUserId()

void setUserId(String? userId)

• userId - User identifier string, or null to clear

​

isInitialized()

Future<bool> isInitialized()

​

setDoNotSell()

void setDoNotSell(bool flag)

• flag - true to opt out of data sale, false to allow

​

setConsent()

void setConsent(bool flag)

• flag - true if user consents, false if user denies

​

VelocityNativeAdRequest

const VelocityNativeAdRequest({
  this.prompt,
  this.aiResponse,
  this.conversationHistory,
  this.additionalContext,
  this.adUnitId,
});

• prompt - User’s query or prompt for contextual targeting
• aiResponse - AI-generated response content for better targeting
• conversationHistory - Previous conversation turns as ConversationMessage list
• additionalContext - Extra context information (e.g., page content, user preferences)
• adUnitId - Optional ad unit identifier for reporting

​

VelocityNativeAdViewRequest

const VelocityNativeAdViewRequest({
  required this.size,
  this.adConfiguration,
  super.prompt,
  super.aiResponse,
  super.conversationHistory,
  super.additionalContext,
  super.adUnitId,
});

• size - Required. The ad view size (VelocityAdViewSize.s, .m, or .l)
• adConfiguration - Optional theming configuration for the ad view
• All parameters from VelocityNativeAdRequest are also available

​

VelocityNativeAd

VelocityNativeAd(VelocityNativeAdRequest adRequest);

Future<void> load();
void destroy();

NativeAdData? data;
Widget? get widget;
VelocityNativeAdListener? listener;
VelocityNativeAdViewListener? viewListener;

• load() - Loads the ad asynchronously. Populates data on success. For VelocityNativeAdViewRequest, also creates a rendered widget accessible via widget. Throws VelocityAdsError on failure.
• destroy() - Releases native resources. Always call when the ad is no longer needed.

• data - NativeAdData? containing all ad creative fields after a successful load()
• widget - Flutter Widget embedding the native ad view. Only available after load() when the request is a VelocityNativeAdViewRequest
• listener - Optional VelocityNativeAdListener for data-only ad events. Set before calling load()
• viewListener - Optional VelocityNativeAdViewListener for SDK-rendered view events. Set before calling load()

​

NativeAdData

​

VelocityNativeAdListener

abstract class VelocityNativeAdListener {
  void onAdLoaded(VelocityNativeAd ad) {}
  void onAdFailedToLoad(VelocityNativeAd ad, VelocityAdsError error) {}
  void onAdImpression(VelocityNativeAd ad) {}
  void onAdClicked(VelocityNativeAd ad) {}
}

​

VelocityNativeAdViewListener

abstract class VelocityNativeAdViewListener {
  void onAdLoaded(VelocityNativeAd ad, Widget adView) {}
  void onAdFailedToLoad(VelocityNativeAd ad, VelocityAdsError error) {}
  void onAdImpression(VelocityNativeAd ad) {}
  void onAdClicked(VelocityNativeAd ad) {}
}

​

VelocityAdViewSize

enum VelocityAdViewSize { s, m, l }

​

AdConfiguration

const AdConfiguration({
  this.colorScheme,
  this.adTypography,
  this.darkTheme,
});

• colorScheme - Custom color palette for light and dark modes
• adTypography - Custom text styles for ad elements
• darkTheme - null to follow system, true/false to force a specific mode

​

AdColorScheme

const AdColorScheme({
  required AdColors light,
  required AdColors dark,
});

​

AdColors

​

AdTypography

​

AdTextStyle

const AdTextStyle({
  required double fontSize,
  AdFontWeight? fontWeight,
});

​

AdFontWeight

​

ConversationMessage

ConversationMessage.user(String content);
ConversationMessage.assistant(String content);

• role - "user" or "assistant"
• content - Message text