@surfside/ads-react 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +127 -0
- package/lib/cjs/index.js +16325 -0
- package/lib/esm/index.js +16299 -0
- package/lib/types/components/SurfsideBanner.d.ts +67 -0
- package/lib/types/components/SurfsideCarousel.d.ts +24 -0
- package/lib/types/components/SurfsideDynamicZone.d.ts +12 -0
- package/lib/types/components/SurfsideProduct.d.ts +1 -0
- package/lib/types/components/SurfsideVideo.d.ts +72 -0
- package/lib/types/components/index.d.ts +5 -0
- package/lib/types/hooks/index.d.ts +4 -0
- package/lib/types/hooks/useSurfDynamicZone.d.ts +7 -0
- package/lib/types/hooks/useSurfsideBanner.d.ts +252 -0
- package/lib/types/hooks/useSurfsideDynamicZone.d.ts +179 -0
- package/lib/types/hooks/useSurfsideProducts.d.ts +215 -0
- package/lib/types/hooks/useSurfsideVideo.d.ts +265 -0
- package/lib/types/index.d.ts +3 -0
- package/lib/types/provider/SurfsideContextProvider.d.ts +140 -0
- package/lib/types/provider/index.d.ts +1 -0
- package/lib/types/types.d.ts +33 -0
- package/lib/types/utils/Analytics.d.ts +73 -0
- package/lib/types/utils/analytics.d.ts +58 -0
- package/lib/types/utils/index.d.ts +1 -0
- package/package.json +34 -0
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import React from 'react';
|
|
2
|
+
import { type ErrResult } from '@surfside/ads-core-client';
|
|
3
|
+
/**
|
|
4
|
+
* Props for the `SurfsideBanner` component. This component handles rendering of banner creatives
|
|
5
|
+
* from Surfside’s ad platform, managing their loading, display, and error states.
|
|
6
|
+
*
|
|
7
|
+
* You can customize styling, stateful UI, and lifecycle callbacks through these props.
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* ```tsx
|
|
11
|
+
* <SurfsideBanner
|
|
12
|
+
* zoneId="my-zone"
|
|
13
|
+
* size={[4, 1]}
|
|
14
|
+
* renderLoading={() => <div>Loading Ad...</div>}
|
|
15
|
+
* renderError={() => <div>No Ad Available</div>}
|
|
16
|
+
* onRender={(id) => console.log(`Rendered banner: ${id}`)}
|
|
17
|
+
* onWin={(id) => console.log(`Win tracked: ${id}`)}
|
|
18
|
+
* />
|
|
19
|
+
* ```
|
|
20
|
+
*/
|
|
21
|
+
export interface ISurfsideBannerProps {
|
|
22
|
+
/**
|
|
23
|
+
* The Zone ID of the advertisement
|
|
24
|
+
*/
|
|
25
|
+
zoneId: string;
|
|
26
|
+
/**
|
|
27
|
+
* The requested size of the banner, in aspect ratio `[w, h]` (e.g., `[4, 1]`)
|
|
28
|
+
*/
|
|
29
|
+
size: [number, number];
|
|
30
|
+
/**
|
|
31
|
+
* Whether or not the banner is enabled. If `false`, the component will render `null`.
|
|
32
|
+
* @default true
|
|
33
|
+
*/
|
|
34
|
+
enabled?: boolean;
|
|
35
|
+
/**
|
|
36
|
+
* Optional render function for the loading state
|
|
37
|
+
*/
|
|
38
|
+
renderLoading?: () => React.ReactNode;
|
|
39
|
+
/**
|
|
40
|
+
* Optional render function for the error or no-ad state
|
|
41
|
+
*/
|
|
42
|
+
renderError?: () => React.ReactNode;
|
|
43
|
+
/**
|
|
44
|
+
* Callback invoked when a banner is successfully rendered
|
|
45
|
+
*/
|
|
46
|
+
onRender?: (bannerId: string) => void;
|
|
47
|
+
/**
|
|
48
|
+
* Callback invoked when a win is tracked
|
|
49
|
+
*/
|
|
50
|
+
onWin?: (bannerId: string) => void;
|
|
51
|
+
/**
|
|
52
|
+
* Callback invoked when an error occurs or no bid is returned
|
|
53
|
+
*/
|
|
54
|
+
onError?: (error: ErrResult) => void;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* SurfsideBanner renders a banner ad using the `useSurfsideBanner` hook. It automatically
|
|
58
|
+
* manages banner fetching, win tracking, and optional UI fallback states.
|
|
59
|
+
*
|
|
60
|
+
* Customize the banner lifecycle using callbacks and optionally inject custom styles
|
|
61
|
+
* or loading/error content.
|
|
62
|
+
*
|
|
63
|
+
* @param {ISurfsideBannerProps} props Props used to configure the banner rendering behavior
|
|
64
|
+
* @returns A responsive ad container that manages display and state transitions
|
|
65
|
+
*/
|
|
66
|
+
export declare const SurfsideBanner: React.FC<ISurfsideBannerProps>;
|
|
67
|
+
export default SurfsideBanner;
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { type NativeRequestBuilder, type RequestBuilder } from '@surfside/ads-core';
|
|
2
|
+
import type { CarouselLimits } from '@surfside/ads-core-web';
|
|
3
|
+
export interface ISurfsideCarouselRenderProps {
|
|
4
|
+
cardMinWidth: number;
|
|
5
|
+
carouselLimits: CarouselLimits;
|
|
6
|
+
nextType: 'page' | 'product';
|
|
7
|
+
}
|
|
8
|
+
export interface ISurfsideCarouselPropsBase extends ISurfsideCarouselRenderProps {
|
|
9
|
+
zoneId: string;
|
|
10
|
+
requestBuilder?: RequestBuilder;
|
|
11
|
+
nativeRequestBuilder?: NativeRequestBuilder;
|
|
12
|
+
recommender?: 'top-products' | 'for-you' | 'past-purchases';
|
|
13
|
+
enabled?: boolean;
|
|
14
|
+
}
|
|
15
|
+
export interface ISurfsideCarouselPropsRecommended extends ISurfsideCarouselPropsBase {
|
|
16
|
+
strategy: 'hybrid' | 'recommended';
|
|
17
|
+
recommender: 'top-products' | 'for-you' | 'past-purchases';
|
|
18
|
+
}
|
|
19
|
+
export interface ISurfsideCarouselPropsSponsored extends ISurfsideCarouselPropsBase {
|
|
20
|
+
strategy: 'sponsored';
|
|
21
|
+
recommender: undefined;
|
|
22
|
+
}
|
|
23
|
+
export type SurfsideCarouselProps = ISurfsideCarouselPropsRecommended | ISurfsideCarouselPropsSponsored;
|
|
24
|
+
export declare const SurfsideCarousel: ({ zoneId, cardMinWidth, carouselLimits, nextType, recommender, requestBuilder, nativeRequestBuilder, enabled, strategy }: SurfsideCarouselProps) => import("react/jsx-runtime").JSX.Element;
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { type ErrResult } from '@surfside/ads-core';
|
|
2
|
+
import { type ISurfsideCarouselRenderProps } from './SurfsideCarousel';
|
|
3
|
+
export interface ISurfsideDynamicZoneComponentProps {
|
|
4
|
+
zoneId: string;
|
|
5
|
+
enabled?: boolean;
|
|
6
|
+
carousel: ISurfsideCarouselRenderProps;
|
|
7
|
+
onError?: (error: ErrResult) => void;
|
|
8
|
+
}
|
|
9
|
+
export declare const SurfsideDynamicZone: ({ zoneId, carousel, enabled, onError }: ISurfsideDynamicZoneComponentProps) => import("react/jsx-runtime").JSX.Element;
|
|
10
|
+
export declare class DynamicZoneUnmountedError extends Error {
|
|
11
|
+
constructor();
|
|
12
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import { type RequestBuilder, type ErrResult } from '@surfside/ads-core-client';
|
|
2
|
+
/**
|
|
3
|
+
* Props for the `SurfsideVideo` component. This component handles rendering of video creatives
|
|
4
|
+
* from Surfside’s ad platform, managing their loading, display, and error states.
|
|
5
|
+
*
|
|
6
|
+
* You can customize styling, stateful UI, and lifecycle callbacks through these props.
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* ```tsx
|
|
10
|
+
* <SurfsideVideo
|
|
11
|
+
* zoneId="my-zone"
|
|
12
|
+
* size={[4, 1]}
|
|
13
|
+
* renderLoading={() => <div>Loading Ad...</div>}
|
|
14
|
+
* renderError={() => <div>No Ad Available</div>}
|
|
15
|
+
* onRender={(id) => console.log(`Rendered video: ${id}`)}
|
|
16
|
+
* onWin={(id) => console.log(`Win tracked: ${id}`)}
|
|
17
|
+
* />
|
|
18
|
+
* ```
|
|
19
|
+
*/
|
|
20
|
+
export interface ISurfsideVideoProps {
|
|
21
|
+
/**
|
|
22
|
+
* The Zone ID of the advertisement
|
|
23
|
+
*/
|
|
24
|
+
zoneId: string;
|
|
25
|
+
/**
|
|
26
|
+
* The requested size of the video, in aspect ratio `[w, h]` (e.g., `[4, 1]`)
|
|
27
|
+
*/
|
|
28
|
+
size: [number, number];
|
|
29
|
+
/**
|
|
30
|
+
* The minimum requested duration of the video, in seconds. If no minimum is set, 0 will be used.
|
|
31
|
+
*
|
|
32
|
+
* @default 0
|
|
33
|
+
*/
|
|
34
|
+
minDuration?: number;
|
|
35
|
+
/**
|
|
36
|
+
* The maxmimum requested duration of the video, in seconds.
|
|
37
|
+
*/
|
|
38
|
+
maxDuration: number;
|
|
39
|
+
/**
|
|
40
|
+
* A list of [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types)
|
|
41
|
+
* requested for the video. If this field is not set, the default value will be `['video/mp4']`.
|
|
42
|
+
*
|
|
43
|
+
* @remarks
|
|
44
|
+
*
|
|
45
|
+
* Currently, Surfside only supports mp4 MIME types, but more formats may be added in the future.
|
|
46
|
+
* You should **always** add `video/mp4` to your MIME types if you specify this field, or your video ads
|
|
47
|
+
* may not work.
|
|
48
|
+
*/
|
|
49
|
+
mimes?: string[];
|
|
50
|
+
/**
|
|
51
|
+
* Whether or not the video is enabled. If `false`, the component will render `null`.
|
|
52
|
+
* @default true
|
|
53
|
+
*/
|
|
54
|
+
enabled?: boolean;
|
|
55
|
+
/**
|
|
56
|
+
* Callback invoked when an error occurs or no bid is returned
|
|
57
|
+
*/
|
|
58
|
+
onError?: (error: ErrResult) => void;
|
|
59
|
+
requestBuilder?: RequestBuilder;
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* SurfsideVideo renders a video ad using the `useSurfsideVideo` hook. It automatically
|
|
63
|
+
* manages video fetching, win tracking, and optional UI fallback states.
|
|
64
|
+
*
|
|
65
|
+
* Customize the video lifecycle using callbacks and optionally inject custom styles
|
|
66
|
+
* or loading/error content.
|
|
67
|
+
*
|
|
68
|
+
* @param {ISurfsideVideoProps} props Props used to configure the video rendering behavior
|
|
69
|
+
* @returns A responsive ad container that manages display and state transitions
|
|
70
|
+
*/
|
|
71
|
+
export declare const SurfsideVideo: ({ zoneId, size, minDuration, maxDuration, mimes, enabled, requestBuilder, onError }: ISurfsideVideoProps) => import("react/jsx-runtime").JSX.Element;
|
|
72
|
+
export default SurfsideVideo;
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import { IUseSurfDynamicZoneOptions, UseSurfDynamicZoneReturn } from '../types';
|
|
2
|
+
/**
|
|
3
|
+
* Hook for working with Surfside dynamic zones
|
|
4
|
+
* Provides data and rendering functions for dynamic content zones
|
|
5
|
+
*/
|
|
6
|
+
export declare const useSurfDynamicZone: ({ zoneId, enabled }: IUseSurfDynamicZoneOptions) => UseSurfDynamicZoneReturn;
|
|
7
|
+
export default useSurfDynamicZone;
|
|
@@ -0,0 +1,252 @@
|
|
|
1
|
+
import { type ErrResult, type IBuiltBannerResponse, type Result } from '@surfside/ads-core-client';
|
|
2
|
+
/**
|
|
3
|
+
* A banner creative returned by `useSurfsideBanner`. `adm` is a string with the HTML content of the banner ready for
|
|
4
|
+
* injection into the DOM. It is recommended that you inject the `adm` field into an HTML element with
|
|
5
|
+
* [`dangerouslySetInnerHTML`](
|
|
6
|
+
* https://react.dev/reference/react-dom/components/common#dangerously-setting-the-inner-html
|
|
7
|
+
* )
|
|
8
|
+
*
|
|
9
|
+
* @expandType IBuiltBannerResponse
|
|
10
|
+
*
|
|
11
|
+
* @example
|
|
12
|
+
* ```tsx
|
|
13
|
+
* const [banner, error, analytics] = useSurfsideBanner({
|
|
14
|
+
* zoneId: 'my-zone',
|
|
15
|
+
* size: [16, 9]
|
|
16
|
+
* });
|
|
17
|
+
*
|
|
18
|
+
* if(banner !== undefined) {
|
|
19
|
+
* return (
|
|
20
|
+
* <div dangerouslySetInnerHTML={{ __html: banner.adm }}></div>
|
|
21
|
+
* );
|
|
22
|
+
* }
|
|
23
|
+
* ```
|
|
24
|
+
*
|
|
25
|
+
* @expandType IBuiltBannerResponse
|
|
26
|
+
*/
|
|
27
|
+
export interface IBanner extends IBuiltBannerResponse {
|
|
28
|
+
/** The ID of the bid response */
|
|
29
|
+
id: string;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* The parameters used to configure `useSurfsideBanner`
|
|
33
|
+
*/
|
|
34
|
+
export interface IUseSurfsideBannerOptions {
|
|
35
|
+
/**
|
|
36
|
+
* The Zone ID of the advertisement
|
|
37
|
+
*/
|
|
38
|
+
zoneId: string;
|
|
39
|
+
/**
|
|
40
|
+
* The requested size of the placement, in aspect ratio [w, h] (i.e, `[16, 9]` or `[4, 1]`)
|
|
41
|
+
*/
|
|
42
|
+
size: [number, number];
|
|
43
|
+
/**
|
|
44
|
+
* Whether or not to request the banner right away. Useful for lazy loading
|
|
45
|
+
* @default true
|
|
46
|
+
*/
|
|
47
|
+
enabled?: boolean;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Callbacks for handling the win event for a banner. Impressions are automatically triggered via tracking pixel
|
|
51
|
+
* when the banner is added to the page and clicks are automatically handled via an `<a>` tag added to the adm field
|
|
52
|
+
* of the banner
|
|
53
|
+
*/
|
|
54
|
+
export interface IBannerAnalyticsCallbacks {
|
|
55
|
+
trackWin: () => void;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* The base return type for {@link useSurfsideBanner}. There are two child interfaces which represent the distinct
|
|
59
|
+
* states of `useSurfsideBanner`: {@link IUseSurfsideBannerReturnSuccess} (for successful states) and
|
|
60
|
+
* {@link IUseSurfsideBannerReturnError} (for error states). For documentation on both, see
|
|
61
|
+
* {@link UseSurfsideBannerReturn}.
|
|
62
|
+
*
|
|
63
|
+
* @expandType IBannerAnalyticsCallbacks
|
|
64
|
+
*
|
|
65
|
+
* @see UseSurfsideBannerReturn
|
|
66
|
+
*/
|
|
67
|
+
export interface IUseSurfsideBannerReturn {
|
|
68
|
+
/**
|
|
69
|
+
* The banner creative and associated data. On success, this will be set to a value. On error, this will be
|
|
70
|
+
* `undefined`.
|
|
71
|
+
*
|
|
72
|
+
* For an example workflow, see {@link IBanner}
|
|
73
|
+
*/
|
|
74
|
+
banner?: IBanner;
|
|
75
|
+
/**
|
|
76
|
+
* Indicates if Surfside ads is still fetching the banner from the bidder. On success and error, this is set to
|
|
77
|
+
* `false`.
|
|
78
|
+
*/
|
|
79
|
+
loading: boolean;
|
|
80
|
+
/**
|
|
81
|
+
* Indicates if there was an error during the bidding process. If the bidder returns no ads, this will be set to
|
|
82
|
+
* {@link NoBidsError}.
|
|
83
|
+
*
|
|
84
|
+
* For an example workflow, see {@link IUseSurfsideBannerReturnError}
|
|
85
|
+
*/
|
|
86
|
+
error?: ErrResult;
|
|
87
|
+
/**
|
|
88
|
+
* Fetch a new banner using the original bid request. Useful for re-auctioning on a fixed interval.
|
|
89
|
+
*
|
|
90
|
+
* `refetch` is always defined; you can call it at any time.
|
|
91
|
+
*
|
|
92
|
+
* If `enabled` is `false` or the provider ins't ready, `refetch` simple returns without making a network request.
|
|
93
|
+
*
|
|
94
|
+
* For an example workflow, see {@link IUseSurfsideBannerReturnSuccess}
|
|
95
|
+
*/
|
|
96
|
+
refetch?: () => Promise<void>;
|
|
97
|
+
/**
|
|
98
|
+
* A set of functions to call for manually handling auction events.
|
|
99
|
+
*
|
|
100
|
+
* If `useSurfsideBanner` succeeds, this property will be set to a value
|
|
101
|
+
*
|
|
102
|
+
* If `useSurfsideBanner` fails with an error state, this will be set to `undefined`.
|
|
103
|
+
*/
|
|
104
|
+
analytics?: IBannerAnalyticsCallbacks;
|
|
105
|
+
}
|
|
106
|
+
/**
|
|
107
|
+
* The success state version of the return type for `useSurfsideBanner`
|
|
108
|
+
*/
|
|
109
|
+
export interface IUseSurfsideBannerReturnSuccess extends IUseSurfsideBannerReturn {
|
|
110
|
+
banner: IBanner;
|
|
111
|
+
loading: false;
|
|
112
|
+
error: undefined;
|
|
113
|
+
analytics: IBannerAnalyticsCallbacks;
|
|
114
|
+
/**
|
|
115
|
+
* Fetch a new banner using the original bid request. Useful for re-auctioning on a fixed interval.
|
|
116
|
+
*
|
|
117
|
+
* `refetch` is always defined; you can call it at any time.
|
|
118
|
+
*
|
|
119
|
+
* If `enabled` is `false` or the provider ins't ready, `refetch` simple returns without making a network request.
|
|
120
|
+
*
|
|
121
|
+
* @example
|
|
122
|
+
* ```tsx
|
|
123
|
+
* const { banner, refetch } = useSurfsideBanner(
|
|
124
|
+
* zoneId: 'my-zone',
|
|
125
|
+
* size: [16, 9]
|
|
126
|
+
* );
|
|
127
|
+
*
|
|
128
|
+
* useEffect(() => {
|
|
129
|
+
* const timer = setTimeout(refetch, 30000); // re-auction in 30s.
|
|
130
|
+
* return () => clearTimeout(timer); // cleanup after next run
|
|
131
|
+
* }, [refetch])
|
|
132
|
+
*
|
|
133
|
+
* return (
|
|
134
|
+
* <div dangerouslySetInnerHTML={{ __html: banner.adm }}></div>
|
|
135
|
+
* );
|
|
136
|
+
* ```
|
|
137
|
+
*/
|
|
138
|
+
refetch: () => Promise<void>;
|
|
139
|
+
}
|
|
140
|
+
/**
|
|
141
|
+
* The error state version of the return type for `useSurfsideBanner`.
|
|
142
|
+
*/
|
|
143
|
+
export interface IUseSurfsideBannerReturnError extends IUseSurfsideBannerReturn {
|
|
144
|
+
banner: undefined;
|
|
145
|
+
/**
|
|
146
|
+
*
|
|
147
|
+
* Indicates if there was an error during the bidding process. If the bidder returns no ads, this will be set to
|
|
148
|
+
* {@link NoBidsError}.
|
|
149
|
+
* @example
|
|
150
|
+
* All errors in surfside ads are class types, so to handle errors, use this pattern
|
|
151
|
+
*
|
|
152
|
+
* ```tsx
|
|
153
|
+
* const { banner, error, loading } = useSurfsideBanner({
|
|
154
|
+
* zoneId: 'my-zone',
|
|
155
|
+
* size: [16, 9]
|
|
156
|
+
* });
|
|
157
|
+
*
|
|
158
|
+
* if(loading) {
|
|
159
|
+
* return <></>;
|
|
160
|
+
* }
|
|
161
|
+
*
|
|
162
|
+
* if (error !== undefined) {
|
|
163
|
+
* if (error instanceof NoBidsError) { // Not a big problem - just don't render anything
|
|
164
|
+
* console.log("Bidder returned nothing - not rendering banner");
|
|
165
|
+
* return <></>;
|
|
166
|
+
* } else { // Actual error - Bidder returned an error code
|
|
167
|
+
* throw error.error; // `error.error` is the actual javascript error type
|
|
168
|
+
* }
|
|
169
|
+
* }
|
|
170
|
+
*
|
|
171
|
+
* // ... render banner here
|
|
172
|
+
* ```
|
|
173
|
+
*/
|
|
174
|
+
error: ErrResult;
|
|
175
|
+
loading: false;
|
|
176
|
+
analytics: undefined;
|
|
177
|
+
refetch: () => Promise<void>;
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* The loading state version of the return type for `useSurfsideBanner`.
|
|
181
|
+
*/
|
|
182
|
+
export interface IUseSurfsideBannerReturnLoading extends IUseSurfsideBannerReturn {
|
|
183
|
+
banner: undefined;
|
|
184
|
+
error: undefined;
|
|
185
|
+
/**
|
|
186
|
+
* Indicates if Surfside ads is still fetching the banner from the bidder. On success and error, this is set to
|
|
187
|
+
* `false`.
|
|
188
|
+
*/
|
|
189
|
+
loading: true;
|
|
190
|
+
analytics: undefined;
|
|
191
|
+
refetch: () => Promise<void>;
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* Discriminated union representing the three output states of {@link useSurfsideBanner}.
|
|
195
|
+
*
|
|
196
|
+
* When `useSurfsideBanner` returns successfully, {@link IUseSurfsideBannerReturnSuccess} returns, and the `banner` and
|
|
197
|
+
* `analytics` fields are given values.
|
|
198
|
+
*
|
|
199
|
+
* If `useSurfsideBanner` fails, {@link IUseSurfsideBannerReturnError} returns, the `banner` and `analytics` fields are
|
|
200
|
+
* set to `undefined`, and the `error` field is given a value.
|
|
201
|
+
* @expandType IUseSurfsideBannerReturnSuccess
|
|
202
|
+
* @expandType IUseSurfsideBannerReturnError
|
|
203
|
+
* @expandType IUseSurfsideBannerReturnLoading
|
|
204
|
+
*/
|
|
205
|
+
export type UseSurfsideBannerReturn = IUseSurfsideBannerReturnSuccess | IUseSurfsideBannerReturnError | IUseSurfsideBannerReturnLoading;
|
|
206
|
+
/**
|
|
207
|
+
* Requests and returns a banner creative. Accepts a size argument and returns an object wrapping the creative markup
|
|
208
|
+
* (called the `adm`) and some analytics callbacks for tracking auction events, as well as metadata such as the original
|
|
209
|
+
* bid response which creatived the banner.
|
|
210
|
+
*
|
|
211
|
+
* For documentation on the return values and possible states of this hook, see {@link UseSurfsideBannerReturn}.
|
|
212
|
+
*
|
|
213
|
+
* @example
|
|
214
|
+
* To request a banner and display it, pass a desired creative aspect ratio and check the status of the hook, then
|
|
215
|
+
* render when the banner has returned successfully
|
|
216
|
+
*
|
|
217
|
+
* ```tsx
|
|
218
|
+
* const { banner, loading, error, analytics } = useSurfsideBanner({
|
|
219
|
+
* zoneId: 'my-zone',
|
|
220
|
+
* size: [4, 1] // 4x1 banner
|
|
221
|
+
* })
|
|
222
|
+
*
|
|
223
|
+
* // Track win event
|
|
224
|
+
* useEffect(() => analytics?.trackWin(banner), [analytics]);
|
|
225
|
+
*
|
|
226
|
+
* if (loading) {
|
|
227
|
+
* return <div>Loading...</div>
|
|
228
|
+
* }
|
|
229
|
+
*
|
|
230
|
+
* if (error !== undefined) {
|
|
231
|
+
* throw error.error; // error.error is the Javascript "Error" type which can be safely thrown
|
|
232
|
+
* }
|
|
233
|
+
*
|
|
234
|
+
* return <div dangerouslySetInnerHTML={{ __html: banner.adm }}></div>;
|
|
235
|
+
* ```
|
|
236
|
+
*
|
|
237
|
+
* @expandType IUseSurfsideBannerOptions
|
|
238
|
+
* @expandType UseSurfsideBannerReturn
|
|
239
|
+
*
|
|
240
|
+
* @param {IUseSurfsideBannerOptions} params
|
|
241
|
+
*/
|
|
242
|
+
export declare const useSurfsideBanner: ({ zoneId, size, enabled }: IUseSurfsideBannerOptions) => UseSurfsideBannerReturn;
|
|
243
|
+
export interface IUseSurfsideBannerResponseProps extends IUseSurfsideBannerOptions {
|
|
244
|
+
banner: Result<IBuiltBannerResponse> | undefined;
|
|
245
|
+
}
|
|
246
|
+
export declare const useSurfsideBannerResponse: (props: IUseSurfsideBannerResponseProps | undefined) => UseSurfsideBannerReturn;
|
|
247
|
+
export declare class InvalidBannerStateError extends Error {
|
|
248
|
+
readonly banner: IBanner | undefined;
|
|
249
|
+
readonly error: ErrResult | undefined;
|
|
250
|
+
readonly loading: boolean;
|
|
251
|
+
constructor(banner: IBanner | undefined, error: ErrResult | undefined, loading: boolean);
|
|
252
|
+
}
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
import { type ErrResult } from '@surfside/ads-core-client';
|
|
2
|
+
import { type IProductIDData, type IProductInfoData, type IUseSurfsideProductsReturnGenericSuccess, type IUseSurfsideBannerReturnSuccess, type UseSurfsideProductsReturn, type UseSurfsideVideoReturn } from '../hooks';
|
|
3
|
+
/**
|
|
4
|
+
* Options for dynamic zones to pass through to the underlying `useSurfsideProducts` hook.
|
|
5
|
+
*/
|
|
6
|
+
export interface IUseSurfsideDynamicZoneOptionsConfigProductOptions {
|
|
7
|
+
/**
|
|
8
|
+
* If true, `useDSurfsideDynamicZone` will map product feed results to their full product data fields, including
|
|
9
|
+
* name, description, price, etc.
|
|
10
|
+
*
|
|
11
|
+
* If false, `useDSurfsideDynamicZone` will return only product IDs
|
|
12
|
+
* @defaultValue true
|
|
13
|
+
*
|
|
14
|
+
*/
|
|
15
|
+
withProductInfo?: boolean;
|
|
16
|
+
pageSize: number;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* @expandType IUseSurfsideDynamicZoneOptionsConfigProductOptions
|
|
20
|
+
*/
|
|
21
|
+
export interface IUseSurfsideDynamicZoneOptionsConfigWithProductInfo extends IUseSurfsideDynamicZoneOptionsConfigProductOptions {
|
|
22
|
+
withProductInfo?: true;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* @expandType IUseSurfsideDynamicZoneOptionsConfigProductOptions
|
|
26
|
+
*/
|
|
27
|
+
export interface IUseSurfsideDynamicZoneOptionsConfigWithProductIDs extends IUseSurfsideDynamicZoneOptionsConfigProductOptions {
|
|
28
|
+
withProductInfo: false;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* @expandType IUseSurfsideDynamicZoneOptionsConfigWithProductInfo
|
|
32
|
+
* @expandType IUseSurfsideDynamicZoneOptionsConfigWithProductIDs
|
|
33
|
+
*/
|
|
34
|
+
export type UseSurfsideDynamicZoneOptionsConfigProductInfo = IUseSurfsideDynamicZoneOptionsConfigWithProductInfo | IUseSurfsideDynamicZoneOptionsConfigWithProductIDs;
|
|
35
|
+
export type UseSurfDynamicZoneOptionsBase = {
|
|
36
|
+
/** The Zone ID for the advertisement */
|
|
37
|
+
zoneId: string;
|
|
38
|
+
/** Whether or not to request the dynamic zone right away. Useful for lazy loading */
|
|
39
|
+
enabled?: boolean;
|
|
40
|
+
};
|
|
41
|
+
/**
|
|
42
|
+
* @expandType UseSurfDynamicZoneOptionsBase
|
|
43
|
+
* @expandType IUseSurfsideDynamicZoneOptionsConfigWithProductInfo
|
|
44
|
+
*/
|
|
45
|
+
export type UseSurfDynamicZoneOptionsWithProductInfo = UseSurfDynamicZoneOptionsBase & IUseSurfsideDynamicZoneOptionsConfigWithProductInfo;
|
|
46
|
+
/**
|
|
47
|
+
* @expandType UseSurfDynamicZoneOptionsBase
|
|
48
|
+
* @expandType IUseSurfsideDynamicZoneOptionsConfigWithProductIDs
|
|
49
|
+
*/
|
|
50
|
+
export type UseSurfDynamicZoneOptionsWithProductIDs = UseSurfDynamicZoneOptionsBase & IUseSurfsideDynamicZoneOptionsConfigWithProductIDs;
|
|
51
|
+
/**
|
|
52
|
+
* @expandType UseSurfDynamicZoneOptionsWithProductIDs
|
|
53
|
+
* @expandType UseSurfDynamicZoneOptionsWithProductInfo
|
|
54
|
+
*/
|
|
55
|
+
export type UseSurfDynamicZoneOptions = UseSurfDynamicZoneOptionsWithProductIDs | UseSurfDynamicZoneOptionsWithProductInfo;
|
|
56
|
+
/**
|
|
57
|
+
* The return type for `useSurfsideDynamicZone`. Returns different creatives in the `data` field depending on the result
|
|
58
|
+
* of the dynamic zone selection process.
|
|
59
|
+
*/
|
|
60
|
+
export interface IUseDynamicZoneReturnBase<T> {
|
|
61
|
+
/**
|
|
62
|
+
* The type of creative returned by the dynamic zone. When the dynamic zone is still loading, this will be
|
|
63
|
+
* `undefined`. If the dynamic zone fails, this will be `undefined`.
|
|
64
|
+
*/
|
|
65
|
+
type?: 'banner' | 'video' | 'products';
|
|
66
|
+
/**
|
|
67
|
+
* Indicates if the dynamic zone is still loading or not. If the dynamic zone is done loading or fails, this will be
|
|
68
|
+
* `false`.
|
|
69
|
+
*/
|
|
70
|
+
loading: boolean;
|
|
71
|
+
/**
|
|
72
|
+
* Indicates if there was an error while loading the dynamic zone. If there was an error, this will be set to a
|
|
73
|
+
* value indicating the type of error
|
|
74
|
+
*/
|
|
75
|
+
error?: ErrResult;
|
|
76
|
+
/**
|
|
77
|
+
* Re-trigger the dynamic zone creative selection process. If the dynamic zone loads successfully, this will be set
|
|
78
|
+
* to a value. If the dynamic zone is still loading or fails, this will be set to `undefined`.
|
|
79
|
+
*
|
|
80
|
+
* @remarks
|
|
81
|
+
*
|
|
82
|
+
* This callback will re-trigger the *creative selection process*. This means that if your dynamic zone can return,
|
|
83
|
+
* for example, a carousel *or* a banner, then calling this function may result in switching creative types (i.e,
|
|
84
|
+
* from banner to carousel), which may be a poor user experience. It is recommended that if you want to enable
|
|
85
|
+
* re-auctioning for the returned creative type, you use the `refetch` callback in the underlying creative type.
|
|
86
|
+
*/
|
|
87
|
+
refetchDynamicZone?: () => Promise<void>;
|
|
88
|
+
/**
|
|
89
|
+
* The returned creative data for the dynamic zone. Either a banner, video, or products response. If the dynamic
|
|
90
|
+
* zone returns successfully, this will be set to a value. If the dynamic zone is still loading or fails, this will
|
|
91
|
+
* be set to `undefined`.
|
|
92
|
+
*/
|
|
93
|
+
data?: T;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* @expandType IUseDynamicZoneReturnBase
|
|
97
|
+
*/
|
|
98
|
+
export interface IUseDynamicZoneReturnSuccess<T> extends IUseDynamicZoneReturnBase<T> {
|
|
99
|
+
type: 'banner' | 'video' | 'products';
|
|
100
|
+
loading: false;
|
|
101
|
+
error: undefined;
|
|
102
|
+
refetchDynamicZone: () => Promise<void>;
|
|
103
|
+
data: T;
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* @expandType IUseDynamicZoneReturnBase
|
|
107
|
+
*/
|
|
108
|
+
export interface IUseDynamicZoneReturnError extends IUseDynamicZoneReturnBase<undefined> {
|
|
109
|
+
type: undefined;
|
|
110
|
+
loading: false;
|
|
111
|
+
error: ErrResult;
|
|
112
|
+
data: undefined;
|
|
113
|
+
}
|
|
114
|
+
export interface IUseDynamicZoneReturnLoading extends IUseDynamicZoneReturnBase<undefined> {
|
|
115
|
+
type: undefined;
|
|
116
|
+
loading: true;
|
|
117
|
+
error: undefined;
|
|
118
|
+
data: undefined;
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* The banner response type for a dynamic zone hook
|
|
122
|
+
* @expandType IUseDynamicZoneReturnSuccess
|
|
123
|
+
*/
|
|
124
|
+
export interface IUseDynamicZoneReturnBanner extends IUseDynamicZoneReturnSuccess<IUseSurfsideBannerReturnSuccess> {
|
|
125
|
+
type: 'banner';
|
|
126
|
+
/**
|
|
127
|
+
* A successful banner response type from the {@link useSurfsideBanner} hook.
|
|
128
|
+
*/
|
|
129
|
+
data: IUseSurfsideBannerReturnSuccess;
|
|
130
|
+
}
|
|
131
|
+
/**
|
|
132
|
+
* @expandType IUseDynamicZoneReturnSuccess
|
|
133
|
+
*/
|
|
134
|
+
export interface IUseDynamicZoneReturnVideo extends IUseDynamicZoneReturnSuccess<UseSurfsideVideoReturn> {
|
|
135
|
+
type: 'video';
|
|
136
|
+
/**
|
|
137
|
+
* A successful video response type from the {@link useSurfsideVideo} hook.
|
|
138
|
+
*/
|
|
139
|
+
data: UseSurfsideVideoReturn;
|
|
140
|
+
}
|
|
141
|
+
/**
|
|
142
|
+
* @expandType IUseDynamicZoneReturnSuccess
|
|
143
|
+
*/
|
|
144
|
+
export interface IUseDynamicZoneReturnProducts<T> extends IUseDynamicZoneReturnSuccess<IUseSurfsideProductsReturnGenericSuccess<T>> {
|
|
145
|
+
type: 'products';
|
|
146
|
+
/**
|
|
147
|
+
* A successful product response type from the {@link useSurfsideProducts} hook. The generic type for this response
|
|
148
|
+
* depends on the value of `withProductInfo` from {@link UseSurfDynamicZoneOptions}.
|
|
149
|
+
*/
|
|
150
|
+
data: IUseSurfsideProductsReturnGenericSuccess<T>;
|
|
151
|
+
}
|
|
152
|
+
export interface IUseDynamicZoneReturnProductsIndeterminate extends IUseDynamicZoneReturnSuccess<UseSurfsideProductsReturn> {
|
|
153
|
+
type: 'products';
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* @expandType IUseDynamicZoneReturnBanner
|
|
157
|
+
* @expandType IUseDynamicZoneReturnVideo
|
|
158
|
+
* @expandType IUseDynamicZoneReturnProducts
|
|
159
|
+
*/
|
|
160
|
+
export type UseSurfDynamicZoneReturnGeneric<T> = IUseDynamicZoneReturnBanner | IUseDynamicZoneReturnVideo | IUseDynamicZoneReturnProducts<T> | IUseDynamicZoneReturnError | IUseDynamicZoneReturnLoading;
|
|
161
|
+
/**
|
|
162
|
+
* @expandType UseSurfDynamicZoneReturnGeneric
|
|
163
|
+
*/
|
|
164
|
+
export type UseSurfDynamicZoneReturn = IUseDynamicZoneReturnBanner | IUseDynamicZoneReturnVideo | IUseDynamicZoneReturnProductsIndeterminate | IUseDynamicZoneReturnError | IUseDynamicZoneReturnLoading;
|
|
165
|
+
export declare function useSurfsideDynamicZone(props: UseSurfDynamicZoneOptionsWithProductInfo): UseSurfDynamicZoneReturnGeneric<IProductInfoData>;
|
|
166
|
+
/**
|
|
167
|
+
* @overload
|
|
168
|
+
*
|
|
169
|
+
* Returns a typed version of the `UseSurfsideDynamicZoneReturn` populated with full product IDs, if products are
|
|
170
|
+
* available. If you pass `withProductInfo: false` to props, this overload will be used.
|
|
171
|
+
* @param {UseSurfDynamicZoneOptionsWithProductIDs} props
|
|
172
|
+
* @expandType UseSurfDynamicZoneOptionsWithProductIDs
|
|
173
|
+
*/
|
|
174
|
+
export declare function useSurfsideDynamicZone(props: UseSurfDynamicZoneOptionsWithProductIDs): UseSurfDynamicZoneReturnGeneric<IProductIDData>;
|
|
175
|
+
export declare function useSurfsideDynamicZone(props: UseSurfDynamicZoneOptions): UseSurfDynamicZoneReturn;
|
|
176
|
+
export declare class InvalidDynamicZoneState extends Error {
|
|
177
|
+
readonly zoneId: string;
|
|
178
|
+
constructor(zoneId: string);
|
|
179
|
+
}
|