@bigcrunch/react-native-ads 0.1.0

package/src/index.ts

@@ -0,0 +1,71 @@
+/**
+ * BigCrunch Mobile Ads SDK for React Native
+ *
+ * @packageDocumentation
+ */
+
+// Main SDK API
+export { BigCrunchAds, default as BigCrunchAdsDefault } from './BigCrunchAds';
+
+// Ad Components and APIs
+export { BigCrunchBannerView, default as BigCrunchBannerViewDefault } from './BigCrunchBannerView';
+export { BigCrunchInterstitial, default as BigCrunchInterstitialDefault } from './BigCrunchInterstitial';
+export { BigCrunchRewarded, default as BigCrunchRewardedDefault } from './BigCrunchRewarded';
+
+// Import defaults for the default export
+import BigCrunchAds from './BigCrunchAds';
+import BigCrunchBannerView from './BigCrunchBannerView';
+import BigCrunchInterstitial from './BigCrunchInterstitial';
+import BigCrunchRewarded from './BigCrunchRewarded';
+
+// Export all types
+export * from './types';
+
+// Re-export commonly used types at top level for convenience
+export type {
+  // Initialization
+  InitializationOptions,
+  Environment,
+
+  // Ad formats and sizes
+  AdFormat,
+  BannerSize,
+  CustomSize,
+
+  // Ad components
+  BigCrunchBannerViewProps,
+  InterstitialAd,
+  RewardedAd,
+
+  // Events
+  AdEvent,
+  AdEventListener,
+  EventSubscription,
+  AdError,
+  AdRevenue,
+
+  // Configuration
+  AppConfig,
+  PlacementConfig,
+
+  // Analytics
+  SessionInfo,
+  DeviceContext,
+} from './types';
+
+// Export error codes enum
+export { AdErrorCode } from './types';
+
+// Version
+export const SDK_VERSION = '0.1.0';
+
+/**
+ * Default export for convenience
+ */
+export default {
+  BigCrunchAds,
+  BigCrunchBannerView,
+  BigCrunchInterstitial,
+  BigCrunchRewarded,
+  SDK_VERSION,
+};

package/src/types/ads.ts

@@ -0,0 +1,112 @@
+/**
+ * Ad-specific types for BigCrunch Mobile Ads SDK
+ */
+
+import { BannerSize, CustomSize, AdRequestOptions, AdEventListener, EventSubscription } from './index';
+
+/**
+ * Banner view props for React component
+ */
+export interface BigCrunchBannerViewProps {
+  /** Placement ID configured in BigCrunch dashboard */
+  placementId: string;
+  /** Banner size (optional, will use placement config if not specified) */
+  size?: BannerSize | CustomSize;
+  /** Whether to load ad automatically when component mounts */
+  autoLoad?: boolean;
+  /** Auto-refresh interval in seconds (0 = disabled) */
+  refreshInterval?: number;
+  /** Custom targeting parameters */
+  customTargeting?: Record<string, string>;
+  /** Style for the banner container */
+  style?: any;
+  /** Callback when ad loads successfully */
+  onAdLoaded?: () => void;
+  /** Callback when ad fails to load */
+  onAdFailedToLoad?: (error: AdError) => void;
+  /** Callback when ad impression is recorded */
+  onAdImpression?: () => void;
+  /** Callback when ad is clicked */
+  onAdClicked?: () => void;
+  /** Callback when ad opens overlay */
+  onAdOpened?: () => void;
+  /** Callback when ad closes overlay */
+  onAdClosed?: () => void;
+  /** Callback when ad revenue is received */
+  onAdRevenue?: (revenue: AdRevenue) => void;
+}
+
+/**
+ * Interstitial ad interface
+ */
+export interface InterstitialAd {
+  /** Load an interstitial ad */
+  load(options: AdRequestOptions): Promise<void>;
+  /** Show the loaded interstitial */
+  show(): Promise<void>;
+  /** Check if ad is loaded and ready to show */
+  isLoaded(): Promise<boolean>;
+  /** Destroy the ad instance */
+  destroy(): void;
+  /** Add event listener */
+  addEventListener<T extends AdEvent>(
+    eventType: T['type'],
+    listener: AdEventListener<T>
+  ): EventSubscription;
+  /** Remove all event listeners */
+  removeAllListeners(): void;
+}
+
+/**
+ * Rewarded ad interface
+ */
+export interface RewardedAd {
+  /** Load a rewarded ad */
+  load(options: AdRequestOptions): Promise<void>;
+  /** Show the loaded rewarded ad */
+  show(): Promise<void>;
+  /** Check if ad is loaded and ready to show */
+  isLoaded(): Promise<boolean>;
+  /** Destroy the ad instance */
+  destroy(): void;
+  /** Add event listener */
+  addEventListener<T extends AdEvent>(
+    eventType: T['type'],
+    listener: AdEventListener<T>
+  ): EventSubscription;
+  /** Remove all event listeners */
+  removeAllListeners(): void;
+}
+
+/**
+ * Native ad data
+ */
+export interface NativeAdData {
+  /** Placement ID */
+  placementId: string;
+  /** Headline text */
+  headline?: string;
+  /** Body text */
+  body?: string;
+  /** Call to action text */
+  callToAction?: string;
+  /** Icon image URL */
+  icon?: string;
+  /** Main image URL */
+  image?: string;
+  /** Advertiser name */
+  advertiser?: string;
+  /** Star rating */
+  starRating?: number;
+  /** Price text */
+  price?: string;
+  /** Store name */
+  store?: string;
+  /** Ad choices icon URL */
+  adChoicesIcon?: string;
+}
+
+/**
+ * Import required types
+ */
+import { AdError, AdRevenue, AdEvent } from './index';

package/src/types/config.ts

@@ -0,0 +1,145 @@
+/**
+ * Configuration types for BigCrunch Mobile Ads SDK
+ */
+
+import { AdFormat } from './index';
+
+/**
+ * App configuration from BigCrunch backend
+ */
+export interface AppConfig {
+  /** Property ID */
+  propertyId: string;
+  /** Property name */
+  propertyName: string;
+  /** List of configured placements */
+  placements: PlacementConfig[];
+  /** Global settings */
+  settings?: GlobalSettings;
+  /** Last updated timestamp */
+  lastUpdated?: string;
+  /** Config version */
+  version?: string;
+}
+
+/**
+ * Individual placement configuration
+ */
+export interface PlacementConfig {
+  /** Unique placement ID */
+  placementId: string;
+  /** Placement name for reporting */
+  placementName?: string;
+  /** Ad format type */
+  format: AdFormat;
+  /** Google Ad Manager ad unit ID */
+  gamAdUnit: string;
+  /** Ad size configuration */
+  size?: AdSizeConfig;
+  /** Prebid configuration */
+  prebidConfig?: PrebidConfig;
+  /** Amazon APS configuration */
+  amazonConfig?: AmazonConfig;
+  /** Placement-specific settings */
+  settings?: PlacementSettings;
+  /** Whether placement is active */
+  enabled: boolean;
+}
+
+/**
+ * Ad size configuration
+ */
+export interface AdSizeConfig {
+  /** Width in dp/points */
+  width: number;
+  /** Height in dp/points */
+  height: number;
+  /** Whether to use adaptive sizing */
+  adaptive?: boolean;
+}
+
+/**
+ * Prebid configuration
+ */
+export interface PrebidConfig {
+  /** Prebid account ID */
+  accountId: string;
+  /** Config ID for server-side configuration */
+  configId: string;
+  /** Timeout for prebid requests in milliseconds */
+  timeout?: number;
+  /** Enable debug mode for prebid */
+  debug?: boolean;
+  /** Custom targeting parameters */
+  customTargeting?: Record<string, string>;
+  /** Price granularity */
+  priceGranularity?: 'low' | 'medium' | 'high' | 'auto' | 'dense' | 'custom';
+  /** Custom price granularity buckets */
+  customPriceGranularity?: PriceGranularityBucket[];
+}
+
+/**
+ * Price granularity bucket configuration
+ */
+export interface PriceGranularityBucket {
+  /** Minimum price */
+  min: number;
+  /** Maximum price */
+  max: number;
+  /** Increment */
+  increment: number;
+}
+
+/**
+ * Amazon APS configuration
+ */
+export interface AmazonConfig {
+  /** Amazon slot ID */
+  slotId: string;
+  /** Enable Amazon integration */
+  enabled: boolean;
+  /** Timeout for Amazon requests */
+  timeout?: number;
+}
+
+/**
+ * Global settings
+ */
+export interface GlobalSettings {
+  /** Enable test mode */
+  testMode?: boolean;
+  /** Test device IDs */
+  testDeviceIds?: string[];
+  /** Enable verbose logging */
+  verboseLogging?: boolean;
+  /** Session timeout in seconds */
+  sessionTimeout?: number;
+  /** Analytics batch size */
+  analyticsBatchSize?: number;
+  /** Analytics flush interval in seconds */
+  analyticsFlushInterval?: number;
+  /** Enable crash reporting */
+  crashReporting?: boolean;
+  /** GDPR consent string */
+  gdprConsent?: string;
+  /** CCPA compliance string */
+  ccpaString?: string;
+  /** COPPA compliance */
+  coppaCompliant?: boolean;
+}
+
+/**
+ * Placement-specific settings
+ */
+export interface PlacementSettings {
+  /** Auto-refresh interval in seconds (0 = disabled) */
+  refreshInterval?: number;
+  /** Maximum refresh count */
+  maxRefreshCount?: number;
+  /** Enable viewability tracking */
+  viewabilityTracking?: boolean;
+  /** Viewability threshold percentage */
+  viewabilityThreshold?: number;
+  /** Custom targeting for this placement */
+  customTargeting?: Record<string, string>;
+}

package/src/types/events.ts

@@ -0,0 +1,337 @@
+/**
+ * Event types for BigCrunch Mobile Ads SDK
+ */
+
+import { AdError, AdRevenue, AdFormat } from './index';
+
+/**
+ * Base event data
+ */
+export interface BaseAdEvent {
+  /** Placement ID */
+  placementId: string;
+  /** Ad format */
+  format: AdFormat;
+  /** Timestamp of the event */
+  timestamp: number;
+}
+
+/**
+ * Ad loaded event
+ */
+export interface AdLoadedEvent extends BaseAdEvent {
+  type: 'adLoaded';
+  /** Ad network that filled the ad */
+  adNetwork?: string;
+  /** Ad unit ID */
+  adUnitId?: string;
+}
+
+/**
+ * Ad failed to load event
+ */
+export interface AdFailedToLoadEvent extends BaseAdEvent {
+  type: 'adFailedToLoad';
+  /** Error details */
+  error: AdError;
+}
+
+/**
+ * Ad impression event
+ */
+export interface AdImpressionEvent extends BaseAdEvent {
+  type: 'adImpression';
+  /** Ad network that served the impression */
+  adNetwork?: string;
+  /** Unique impression ID (UUID) */
+  impressionId?: string;
+  /** GAM ad unit path */
+  gamAdUnit?: string;
+  /** Ad size (e.g., "320x50") */
+  adSize?: string;
+  /** Auction ID from Prebid */
+  auctionId?: string;
+  /** Winning bidder name */
+  bidder?: string;
+  /** Bid price in CPM */
+  bidPriceCpm?: number;
+  /** Advertiser ID from GAM metadata */
+  advertiserId?: string;
+  /** Campaign ID from GAM metadata (not available in mobile SDKs) */
+  campaignId?: string;
+  /** Line item ID from GAM metadata (not available in mobile SDKs) */
+  lineItemId?: string;
+  /** Creative ID from GAM metadata */
+  creativeId?: string;
+  /** Refresh count for this placement */
+  refreshCount?: number;
+  /** Demand channel (e.g., "Prebid Header", "GAM Direct") */
+  demandChannel?: string;
+}
+
+/**
+ * Ad clicked event
+ */
+export interface AdClickedEvent extends BaseAdEvent {
+  type: 'adClicked';
+}
+
+/**
+ * Ad opened event (for overlays/modals)
+ */
+export interface AdOpenedEvent extends BaseAdEvent {
+  type: 'adOpened';
+}
+
+/**
+ * Ad closed event
+ */
+export interface AdClosedEvent extends BaseAdEvent {
+  type: 'adClosed';
+}
+
+/**
+ * Ad revenue event (ILRD)
+ */
+export interface AdRevenueEvent extends BaseAdEvent {
+  type: 'adRevenue';
+  /** Revenue data */
+  revenue: AdRevenue;
+}
+
+/**
+ * Ad viewable event
+ */
+export interface AdViewableEvent extends BaseAdEvent {
+  type: 'adViewable';
+  /** Duration in view (milliseconds) */
+  viewDuration?: number;
+  /** Percentage of ad visible */
+  visiblePercentage?: number;
+}
+
+/**
+ * Rewarded ad events
+ */
+export interface RewardedAdEarnedEvent extends BaseAdEvent {
+  type: 'rewardEarned';
+  /** Reward type */
+  rewardType: string;
+  /** Reward amount */
+  rewardAmount: number;
+}
+
+/**
+ * Union type of all ad events
+ */
+export type AdEvent =
+  | AdLoadedEvent
+  | AdFailedToLoadEvent
+  | AdImpressionEvent
+  | AdClickedEvent
+  | AdOpenedEvent
+  | AdClosedEvent
+  | AdRevenueEvent
+  | AdViewableEvent
+  | RewardedAdEarnedEvent;
+
+/**
+ * Event listener callback
+ */
+export type AdEventListener<T extends AdEvent = AdEvent> = (event: T) => void;
+
+/**
+ * Event subscription
+ */
+export interface EventSubscription {
+  /** Remove the event listener */
+  remove: () => void;
+}
+
+/**
+ * Analytics event for backend
+ *
+ * Note: This represents the legacy event format. The SDK now uses web schema events
+ * with flattened structure (PageViewEvent, ImpressionEvent, ClickEvent, etc.)
+ *
+ * @deprecated Use web schema event types instead
+ */
+export interface AnalyticsEvent {
+  /** Event type */
+  eventType: 'screen_view' | 'ad_request' | 'ad_impression' | 'ad_click' | 'ad_revenue' | 'ad_viewable' | 'session_start' | 'session_end';
+  /** Event timestamp (milliseconds since epoch) */
+  timestamp: number;
+  /** Session ID */
+  sessionId: string;
+  /** Event-specific data */
+  data: Record<string, any>;
+  /** Device context */
+  deviceContext?: Partial<DeviceContext>;
+}
+
+/**
+ * Web schema common fields (present in all events)
+ */
+export interface WebSchemaCommonFields {
+  /** Payload version identifier */
+  payloadVersion: string;
+  /** Config version from backend */
+  configVersion?: string;
+  /** Event timestamp in ISO 8601 format (e.g., "2025-01-15T10:30:00Z") */
+  browserTimestamp: string;
+  /** Session ID (UUID) */
+  sessionId: string;
+  /** User ID (UUID, persistent across sessions) */
+  userId: string;
+  /** Property ID from BigCrunch dashboard */
+  propertyId: string;
+  /** True if this is user's first session */
+  newUser: boolean;
+  /** Current page/screen ID (UUID) */
+  pageId: string;
+  /** Number of page views in current session */
+  sessionDepth: number;
+  /** Browser/SDK identifier (e.g., "BigCrunch iOS SDK 1.0.0") */
+  browser: string;
+  /** Device type (e.g., "iPhone 14", "Samsung Galaxy S21") */
+  device: string;
+  /** Operating system (e.g., "iOS 16.0", "Android 13") */
+  os: string;
+  /** Country code (ISO 3166-1 alpha-2, e.g., "US") */
+  country: string;
+  /** Region/state code */
+  region: string;
+  /** Session attribution source */
+  sessionSource: string;
+  /** Session attribution medium */
+  sessionMedium: string;
+  /** UTM source parameter */
+  utmSource?: string;
+  /** UTM medium parameter */
+  utmMedium?: string;
+  /** UTM campaign parameter */
+  utmCampaign?: string;
+  /** UTM term parameter */
+  utmTerm?: string;
+  /** UTM content parameter */
+  utmContent?: string;
+  /** Google Click ID for attribution */
+  gclid?: string;
+  /** Facebook Click ID for attribution */
+  fbclid?: string;
+}
+
+/**
+ * Page view event (web schema)
+ * Sent to /pageviews endpoint
+ */
+export interface PageViewEvent extends WebSchemaCommonFields {
+  /** Screen/page name */
+  screenName: string;
+  /** Referrer (previous screen) */
+  referrer?: string;
+}
+
+/**
+ * Impression event (web schema)
+ * Sent to /impressions endpoint
+ * Consolidates ad request, impression, and revenue tracking
+ */
+export interface ImpressionEvent extends WebSchemaCommonFields {
+  /** Unique impression ID (UUID) */
+  impressionId: string;
+  /** Placement identifier */
+  placementId: string;
+  /** GAM ad unit path */
+  gamAdUnit: string;
+  /** Ad format (banner, interstitial, rewarded) */
+  format: string;
+  /** Auction ID from Prebid */
+  auctionId?: string;
+  /** Refresh count for this placement */
+  refreshCount?: number;
+  /** Winning bidder name */
+  bidder?: string;
+  /** Ad size (e.g., "320x50") */
+  adSize?: string;
+  /** Bid price/revenue in CPM */
+  bidPriceCpm?: number;
+  /** Floor price */
+  floorPrice?: number;
+  /** Minimum bid to win */
+  minBidToWin?: number;
+  /** Advertiser ID from GAM */
+  advertiserId?: string;
+  /** Campaign ID from GAM (not available in mobile SDKs) */
+  campaignId?: string;
+  /** Line item ID from GAM (not available in mobile SDKs) */
+  lineItemId?: string;
+  /** Creative ID from GAM response */
+  creativeId?: string;
+  /** Amazon bid data */
+  amznBid?: string;
+  /** Amazon price data */
+  amznPrice?: string;
+  /** Demand type (banner, video, etc.) */
+  demandType?: string;
+  /** Demand channel (e.g., "Prebid Header", "GAM Direct") */
+  demandChannel?: string;
+}
+
+/**
+ * Click event (web schema)
+ * Sent to /clicks endpoint
+ */
+export interface ClickEvent extends WebSchemaCommonFields {
+  /** Reference to the impression that was clicked */
+  impressionId: string;
+  /** Placement identifier */
+  placementId: string;
+  /** Ad format */
+  format: string;
+}
+
+/**
+ * Viewability event (web schema)
+ * Sent to /viewability endpoint
+ */
+export interface ViewabilityEvent extends WebSchemaCommonFields {
+  /** Reference to the impression */
+  impressionId: string;
+  /** Placement identifier */
+  placementId: string;
+  /** Ad format */
+  format: string;
+  /** Time ad was viewable in milliseconds */
+  viewableTimeMs: number;
+  /** Percentage of ad that was visible */
+  percentVisible: number;
+}
+
+/**
+ * Engagement event (web schema)
+ * Sent to /engagement endpoint
+ */
+export interface EngagementEvent extends WebSchemaCommonFields {
+  /** Time actively engaged in seconds */
+  engagedTime: number;
+  /** Total time on page/screen in seconds */
+  timeOnPage: number;
+}
+
+/**
+ * Screen view event data
+ */
+export interface ScreenViewData {
+  /** Screen name */
+  screenName: string;
+  /** Screen class/component name */
+  screenClass?: string;
+  /** Previous screen */
+  previousScreen?: string;
+}
+
+/**
+ * Device context (imported from index)
+ */
+import { DeviceContext } from './index';