@ai-ad-network/frontend-sdk 1.0.10 → 1.1.0

package/dist/analytics/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Analytics API - 框架无关的核心模块
+ *
+ * React 和 Universal SDK 共享此模块
+ * 用于发送广告展示和点击事件到 Backend Analytics API
+ */
+import type { ImpressionEventData, ClickEventData, ImpressionResponse, ClickResponse, SessionConfig, AnalyticsSendConfig } from '../types/analytics';
+/**
+ * Session 管理器
+ */
+export declare class SessionManager {
+    private sessionKey;
+    private storage;
+    private memoryCache;
+    constructor(config?: SessionConfig);
+    /**
+     * 获取 Session ID
+     */
+    getSessionId(): string;
+    /**
+     * 重新生成 Session ID
+     */
+    regenerateSessionId(): string;
+    /**
+     * 生成新的 Session ID
+     */
+    private generateSessionId;
+    /**
+     * 清除 Session ID
+     */
+    clearSessionId(): void;
+}
+/**
+ * 获取 Session ID（便捷方法）
+ */
+export declare const getSessionId: () => string;
+/**
+ * Analytics 发送器类
+ */
+export declare class AnalyticsSender {
+    private baseUrl;
+    private timeout;
+    private retryAttempts;
+    private retryDelay;
+    private debug;
+    constructor(config?: AnalyticsSendConfig);
+    /**
+     * 发送广告展示事件
+     */
+    trackImpression(data: ImpressionEventData): Promise<ImpressionResponse | null>;
+    /**
+     * 发送广告点击事件
+     */
+    trackClick(data: ClickEventData): Promise<ClickResponse | null>;
+    /**
+     * 通用请求发送方法（带重试）
+     */
+    private sendRequest;
+    /**
+     * 延迟辅助方法
+     */
+    private delay;
+}
+/**
+ * 发送广告展示事件（便捷方法）
+ */
+export declare const trackAdImpression: (data: ImpressionEventData) => Promise<ImpressionResponse | null>;
+/**
+ * 发送广告点击事件（便捷方法）
+ */
+export declare const trackAdClick: (data: ClickEventData) => Promise<ClickResponse | null>;
+/**
+ * 生成 View Token（用于展示去重）
+ */
+export declare function generateViewToken(adId: string, sessionId: string): string;
+/**
+ * 批量发送展示事件
+ */
+export declare function trackImpressionsBatch(events: ImpressionEventData[]): Promise<(ImpressionResponse | null)[]>;
+/**
+ * 批量发送点击事件
+ */
+export declare function trackClicksBatch(events: ClickEventData[]): Promise<(ClickResponse | null)[]>;
+/**
+ * 创建带配置的 Analytics 实例
+ */
+export declare function createAnalytics(config: AnalyticsSendConfig): {
+    trackImpression: (data: ImpressionEventData) => Promise<ImpressionResponse | null>;
+    trackClick: (data: ClickEventData) => Promise<ClickResponse | null>;
+};
+/**
+ * 创建带配置的 Session 实例
+ */
+export declare function createSession(config?: SessionConfig): {
+    getSessionId: () => string;
+    regenerateSessionId: () => string;
+    clearSessionId: () => void;
+};
+export type { ImpressionEventData, ClickEventData, ImpressionResponse, ClickResponse, SessionConfig, AnalyticsSendConfig, };

package/dist/components/ActionCardAd.d.ts

@@ -24,3 +24,37 @@ export interface ActionCardAdProps {
  * ```
  */
 export declare function ActionCardAd({ ad, variant, className, isLoading, onClick, onImpression, }: ActionCardAdProps): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * ActionCardAdV2 Props
+ */
+export interface ActionCardAdV2Props {
+    ad: KoahAd;
+    variant?: ActionCardVariant;
+    className?: string;
+    isLoading?: boolean;
+    requestId: string;
+    slotId: string;
+    position: number;
+    totalAds: number;
+    onClick?: () => void;
+    onImpression?: () => void;
+}
+/**
+ * ActionCardAdV2 - Action Card component with Analytics API tracking
+ *
+ * Uses the new Analytics API (POST /api/v1/ads/impression, POST /api/v1/ads/click)
+ * instead of pixel tracking.
+ *
+ * @example
+ * ```tsx
+ * <ActionCardAdV2
+ *   ad={ad}
+ *   requestId="req-123"
+ *   slotId="slot-action-card"
+ *   position={0}
+ *   totalAds={3}
+ *   variant="horizontal"
+ * />
+ * ```
+ */
+export declare function ActionCardAdV2({ ad, variant, className, isLoading, requestId, slotId, position, totalAds, onClick, onImpression, }: ActionCardAdV2Props): import("react/jsx-runtime").JSX.Element | null;

package/dist/hooks/useAdTracking.d.ts

@@ -57,3 +57,41 @@ export declare function useClickTracking(ad: KoahAd | null, options?: Pick<AdTra
     handleClick: (e: React.MouseEvent | MouseEvent) => void;
     isClicking: boolean;
 };
+/**
+ * useAdTrackingV2 - Hook for ad impression and click tracking with Analytics API
+ *
+ * Uses the new Analytics API (POST /api/v1/ads/impression, POST /api/v1/ads/click)
+ * instead of pixel tracking.
+ *
+ * @example
+ * ```tsx
+ * const { impressionRef, handleClick, hasImpressed } = useAdTrackingV2<HTMLDivElement>({
+ *   ad,
+ *   requestId: 'req-123',
+ *   slotId: 'slot-action-card',
+ *   position: 0,
+ *   totalAds: 3,
+ *   onImpression: () => console.log('Ad viewed!'),
+ *   onClick: () => console.log('Ad clicked!'),
+ * });
+ * ```
+ */
+export interface UseAdTrackingV2Params {
+    ad: KoahAd;
+    requestId: string;
+    slotId: string;
+    position: number;
+    totalAds: number;
+    intersectionThreshold?: number;
+    minViewTimeMs?: number;
+    onClick?: () => void;
+    onImpression?: () => void;
+}
+export interface UseAdTrackingV2Result {
+    impressionRef: React.RefObject<HTMLElement>;
+    handleClick: (e: React.MouseEvent) => void;
+    hasImpressed: boolean;
+    isIntersecting: boolean;
+    impressionTrackingSent: boolean;
+}
+export declare function useAdTrackingV2<T extends HTMLElement = HTMLDivElement>(params: UseAdTrackingV2Params): UseAdTrackingV2Result;

package/dist/index.d.ts

@@ -27,10 +27,12 @@ export * from './types';
 export type { ConversationMessage, UserProfile, ResponseMetadata, SlotDecisionMetadata, } from './types';
 export { useAiAds, useAiAdsLazy, useAiAdsInfinite } from './hooks/useAiAds';
 export { useAdSlots, useAdSlot, useChatWithAds, adaptAdToKoahAd, fetchAds } from './hooks/useAdSlots';
-export { useAdTracking, useAdTrackingMultiple, useClickTracking, } from './hooks/useAdTracking';
+export { useAdTracking, useAdTrackingV2, useAdTrackingMultiple, useClickTracking, } from './hooks/useAdTracking';
+export type { UseAdTrackingV2Params, UseAdTrackingV2Result, } from './hooks/useAdTracking';
 export { useAdConfig } from './components/AdProvider';
 export { AdLogger, createLogger } from './components/AdProvider';
-export { ActionCardAd } from './components/ActionCardAd';
+export { ActionCardAd, ActionCardAdV2 } from './components/ActionCardAd';
+export type { ActionCardAdV2Props } from './components/ActionCardAd';
 export { EnhancedContent, EnhancedContentInline, EnhancedContentBlock, useEntityStats, } from './components/EnhancedContent';
 export { SuffixAd, SuffixAdInline, SuffixAdMinimal, } from './components/SuffixAd';
 export { FollowUpAd, FollowUpAdMixed, } from './components/FollowUpAd';
@@ -44,6 +46,8 @@ export { AdProvider } from './components/AdProvider';
 export { AdErrorBoundary, withAdErrorBoundary, AdErrorHandler, } from './components/AdErrorBoundary';
 export { AdSkeleton, InlineLoading, DotsLoading, FullPageLoading, } from './components/AdSkeleton';
 export { trackImpression, trackClick, hashUserId, checkFrequencyControl, recordImpression, getSessionId, } from './utils/tracking';
+export { trackAdImpression, trackAdClick, trackImpressionsBatch, trackClicksBatch, generateViewToken, getSessionId as getAnalyticsSessionId, SessionManager, AnalyticsSender, createAnalytics, createSession, } from './analytics';
+export type { ImpressionEventData, ClickEventData, ImpressionResponse, ClickResponse, AdAnalyticsInfo, AdSlotInfo, SessionConfig, AnalyticsSendConfig, } from './types/analytics';
 export { textWeaver, TextWeaver } from './utils/text-weaver';
 export { cn } from './lib/cn';
 export { ClientInfoCollector, getClientInfoCollector, getClientInfo, getDeviceInfo, getUserInfo, getAppInfo, getGeoInfo, getUserId, clearClientInfoCache, getClientInfoJSON, getClientInfoSummary, } from './client-info';