@ai-ad-network/frontend-sdk 1.0.9 → 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/components/AdProvider.d.ts

@@ -5,7 +5,7 @@ import React, { ReactNode } from 'react';
 export interface AdConfig {
     /** Base URL for API requests */
     apiBaseUrl?: string;
-    /** API Key for authentication (format: ak_tenant_key) */
+    /** API Key for authentication (format: ak_<name>_<tier>_<hash>) */
     apiKey?: string;
     /** Default ad formats to request */
     defaultFormats?: string[];
@@ -57,7 +57,7 @@ export interface AdProviderProps {
  *     <AdProvider
  *       config={{
  *         apiBaseUrl: 'https://api.example.com/v1',
- *         apiKey: 'ak_your_tenant_your_key',
+ *         apiKey: 'ak_chatbox_growth_k8Hj3mN9pQ2rT5vY8xZ1cD4fG6hJ9kLm',
  *         enabled: true,
  *         debug: process.env.NODE_ENV === 'development',
  *       }}

package/dist/hooks/useAdSlots.d.ts

@@ -137,7 +137,7 @@ export declare function useChatWithAds(options: {
  * Automatically injects client information for OpenRTB compliance.
  *
  * @param params - Ad request parameters
- * @param options - Additional options (apiBaseUrl, etc.)
+ * @param options - Additional options (apiBaseUrl, apiKey, etc.)
  * @returns Promise resolving to ad response batch
  *
  * @example
@@ -150,7 +150,7 @@ export declare function useChatWithAds(options: {
  *     { slotId: 'slot-source', format: 'source', ... },
  *     { slotId: 'slot-static', format: 'static', ... }
  *   ]
- * });
+ * }, { apiKey: 'ak_xxx' });
  *
  * // Post-response stage (query + response available)
  * const postResponse = await fetchAds({
@@ -167,7 +167,7 @@ export declare function useChatWithAds(options: {
  *     { slotId: 'slot-suffix', format: 'suffix', ... },
  *     { slotId: 'slot-action_card', format: 'action_card', ... }
  *   ]
- * });
+ * }, { apiKey: 'ak_xxx' });
  * ```
  */
 export declare function fetchAds(params: {
@@ -176,4 +176,5 @@ export declare function fetchAds(params: {
     slots: AdSlotRequest[];
 }, options?: {
     apiBaseUrl?: string;
+    apiKey?: string;
 }): Promise<AdResponseBatch>;

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/hooks/useAiAds.d.ts

@@ -7,6 +7,8 @@ import type { KoahAd, IntentResult, RoutingInfo, UseAiAdsOptions, UseAiAdsResult
  * 2. A user query is present
  * 3. The hook is enabled
  *
+ * Uses the unified /api/v1/ads/request endpoint with auto-injected ClientInfo.
+ *
  * @example
  * ```tsx
  * const { ads, intent, isLoading, error } = useAiAds(
@@ -21,6 +23,8 @@ export declare function useAiAds(userQuery: string, aiResponse: string, isStream
 /**
  * useAiAdsLazy - Lazy variant that fetches on demand
  *
+ * Uses the unified /api/v1/ads/request endpoint with auto-injected ClientInfo.
+ *
  * @example
  * ```tsx
  * const { fetchAds, ads, isLoading } = useAiAdsLazy();

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';