@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 ADDED
@@ -0,0 +1,127 @@
1
+ ## Core Library Elements
2
+
3
+ ## Design Architecture
4
+
5
+ The library follows a modern, modular React architecture with two primary layers:
6
+
7
+ 1. **Provider**: `SurfsideProvider` – Initializes the Surfside Ads SDK and manages shared global context.
8
+ 2. **Hooks**: Custom hooks that encapsulate ad fetching, rendering logic, state management, and analytics.
9
+
10
+ This separation of concerns allows for clean and extensible integration across a variety of use cases.
11
+
12
+ ## Quick Start
13
+
14
+ ### Installation
15
+
16
+ ```bash
17
+ # Using npm
18
+ npm install @surfside/ads-react
19
+
20
+ # Using yarn
21
+ yarn add @surfside/ads-react
22
+
23
+ # Using bun
24
+ bun add @surfside/ads-react
25
+ ```
26
+
27
+ ### Basic Usage
28
+
29
+ 1. **Wrap your application with `SurfsideProvider`** to provide the necessary context.
30
+
31
+ ```tsx
32
+ export default function App() {
33
+ return (
34
+ <html lang="en">
35
+ <head>
36
+ {/* Head Content */}
37
+ </head>
38
+ <body>
39
+ <SurfsideProvider
40
+ channelId='XXXXX'
41
+ accountId='XXXXX'
42
+ siteId='XXXXX'
43
+ locationId='surfside-nyc'
44
+ userId='surfside-007'
45
+ >
46
+ <div>
47
+ {/* Application Content */}
48
+ </div>
49
+ </SurfsideProvider>
50
+ </body>
51
+ </html>
52
+ );
53
+ }
54
+ ```
55
+
56
+ 2. **Render a banner ad using the `useSurfsideBanner` hook**.
57
+
58
+ ```tsx
59
+ const Homepage = () => {
60
+ const {
61
+ banner,
62
+ loading,
63
+ error,
64
+ analytics
65
+ } = useSurfsideBanner({
66
+ zoneId: 'XXXXX',
67
+ size: [4,1 ]
68
+ });
69
+
70
+ useEffect(() => {
71
+ analytics?.trackWin();
72
+ }, [analytics]);
73
+
74
+ if (loading) {
75
+ return <BannerSkeleton/>;
76
+ }
77
+
78
+ if (error) {
79
+ return <FallbackComponent/>;
80
+ }
81
+
82
+ return (
83
+ <div>
84
+ <h1>Welcome!</h1>
85
+ <MenuBar/>
86
+ {/* Banner Ad right below the menu bar */}
87
+ <div dangerouslySetInnerHTML={{__html: banner.adm}}></div>
88
+ {/* ... webpage content */}
89
+ </div>
90
+ );
91
+ };
92
+ ```
93
+
94
+ ## Where to start
95
+
96
+ Follow these guides to set up your Surfside Ads implementation
97
+
98
+ * [Surfside API Provider Implementation Guide](../documents/_surfside_ads-react.Implementation_Guides.Surfside_Provider.html)
99
+
100
+ * [Banner Implementation Guide](../documents/_surfside_ads-react.Implementation_Guides.Banner_Ads.html)
101
+
102
+ * [Video Implementation Guide](../documents/_surfside_ads-react.Implementation_Guides.Video_Ads.html)
103
+
104
+ * [Product Feed Implementation Guide](../documents/_surfside_ads-react.Implementation_Guides.Sponsored_and_Recommended_Products.html)
105
+
106
+ * [Dynamic Zone Integration Guide](../documents/_surfside_ads-react.Implementation_Guides.Dynamic_Zones.html)
107
+
108
+ ## Performance & Compatibility
109
+
110
+ The `@surfside/ads-react` library is designed to be **client-side only**. All hooks and rendering logic must run in the browser as access to the browser API is required for bid requests to function correctly. Server-side rendering (SSR) is **not supported yet**, and attempting to use hooks or providers on the server will result in runtime errors.
111
+
112
+ To avoid hydration issues, always ensure components using Surfside hooks are rendered only after the client has mounted.
113
+
114
+
115
+ ```tsx
116
+ const IsClientOnly = ({ children }: { children: React.ReactNode }) => {
117
+ const [ready, setReady] = React.useState(false);
118
+ React.useEffect(() => setReady(true), []);
119
+ return ready ? <>{children}</> : null;
120
+ };
121
+ ```
122
+
123
+ You can wrap Surfside components in a guard like this if needed.
124
+
125
+ ## License
126
+
127
+ Copyright © 2025 Surfside. All rights reserved.