@surfside/ads-react 0.2.0 → 0.3.0-c5bdf731.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 -127
- package/lib/cjs/BuildInfo.js +3 -3
- package/lib/cjs/BuildInfo.js.map +1 -1
- package/lib/esm/BuildInfo.js +3 -3
- package/lib/esm/BuildInfo.js.map +1 -1
- package/package.json +49 -49
package/README.md
CHANGED
|
@@ -1,127 +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.
|
|
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.
|
package/lib/cjs/BuildInfo.js
CHANGED
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.VersionInfo = void 0;
|
|
4
4
|
exports.VersionInfo = {
|
|
5
|
-
'buildBranch': '
|
|
6
|
-
'buildHash': '
|
|
7
|
-
'buildVer': '0.
|
|
5
|
+
'buildBranch': 'HEAD',
|
|
6
|
+
'buildHash': 'c5bdf73',
|
|
7
|
+
'buildVer': '0.3.0-c5bdf731.0'
|
|
8
8
|
};
|
|
9
9
|
//# sourceMappingURL=BuildInfo.js.map
|
package/lib/cjs/BuildInfo.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"BuildInfo.js","sourceRoot":"../@surfside-ads-react/","sources":["BuildInfo.ts"],"names":[],"mappings":";;;AAAa,QAAA,WAAW,GAAG;IACvB,aAAa,EAAE,
|
|
1
|
+
{"version":3,"file":"BuildInfo.js","sourceRoot":"../@surfside-ads-react/","sources":["BuildInfo.ts"],"names":[],"mappings":";;;AAAa,QAAA,WAAW,GAAG;IACvB,aAAa,EAAE,MAAM;IACrB,WAAW,EAAE,SAAS;IACtB,UAAU,EAAE,kBAAkB;CACjC,CAAC"}
|
package/lib/esm/BuildInfo.js
CHANGED
package/lib/esm/BuildInfo.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"BuildInfo.js","sourceRoot":"../@surfside-ads-react/","sources":["BuildInfo.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG;IACvB,aAAa,EAAE,
|
|
1
|
+
{"version":3,"file":"BuildInfo.js","sourceRoot":"../@surfside-ads-react/","sources":["BuildInfo.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG;IACvB,aAAa,EAAE,MAAM;IACrB,WAAW,EAAE,SAAS;IACtB,UAAU,EAAE,kBAAkB;CACjC,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,49 +1,49 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@surfside/ads-react",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "React components for Surfside Ads",
|
|
5
|
-
"main": "./lib/cjs/index.js",
|
|
6
|
-
"module": "./lib/esm/index.js",
|
|
7
|
-
"types": "./lib/types/index.d.ts",
|
|
8
|
-
"exports": {
|
|
9
|
-
".": {
|
|
10
|
-
"import": "./lib/esm/index.js",
|
|
11
|
-
"require": "./lib/cjs/index.js",
|
|
12
|
-
"types": "./lib/types/index.d.ts"
|
|
13
|
-
}
|
|
14
|
-
},
|
|
15
|
-
"type": "module",
|
|
16
|
-
"license": "UNLICENSED",
|
|
17
|
-
"files": [
|
|
18
|
-
"lib/",
|
|
19
|
-
"README.md"
|
|
20
|
-
],
|
|
21
|
-
"scripts": {
|
|
22
|
-
"clean": "rm -rf ./lib",
|
|
23
|
-
"build": "bun x npm-run-all --parallel \"types\" \"esm\" \"cjs\"",
|
|
24
|
-
"types": "tsc -p ./tsconfig.types.json",
|
|
25
|
-
"esm": "tsc -p ./tsconfig.esm.json",
|
|
26
|
-
"cjs": "tsc -p tsconfig.cjs.json",
|
|
27
|
-
"lint": "npx eslint",
|
|
28
|
-
"test": "bunx playwright test",
|
|
29
|
-
"test:ui": "bunx playwright test --ui"
|
|
30
|
-
},
|
|
31
|
-
"peerDependencies": {
|
|
32
|
-
"react": ">=17",
|
|
33
|
-
"react-dom": ">=17",
|
|
34
|
-
"typescript": "^5.8.3"
|
|
35
|
-
},
|
|
36
|
-
"dependencies": {
|
|
37
|
-
"@surfside/ads-core-
|
|
38
|
-
"@surfside/ads-core-
|
|
39
|
-
},
|
|
40
|
-
"devDependencies": {
|
|
41
|
-
"@playwright/test": "^1.60.0",
|
|
42
|
-
"@types/bun": "latest",
|
|
43
|
-
"@types/react": "^19.0.0",
|
|
44
|
-
"@types/react-dom": "^19.0.0",
|
|
45
|
-
"react": "^19.0.0",
|
|
46
|
-
"react-dom": "^19.0.0",
|
|
47
|
-
"typedoc": "^0.28.5"
|
|
48
|
-
}
|
|
49
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@surfside/ads-react",
|
|
3
|
+
"version": "0.3.0-c5bdf731.0",
|
|
4
|
+
"description": "React components for Surfside Ads",
|
|
5
|
+
"main": "./lib/cjs/index.js",
|
|
6
|
+
"module": "./lib/esm/index.js",
|
|
7
|
+
"types": "./lib/types/index.d.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"import": "./lib/esm/index.js",
|
|
11
|
+
"require": "./lib/cjs/index.js",
|
|
12
|
+
"types": "./lib/types/index.d.ts"
|
|
13
|
+
}
|
|
14
|
+
},
|
|
15
|
+
"type": "module",
|
|
16
|
+
"license": "UNLICENSED",
|
|
17
|
+
"files": [
|
|
18
|
+
"lib/",
|
|
19
|
+
"README.md"
|
|
20
|
+
],
|
|
21
|
+
"scripts": {
|
|
22
|
+
"clean": "rm -rf ./lib",
|
|
23
|
+
"build": "bun x npm-run-all --parallel \"types\" \"esm\" \"cjs\"",
|
|
24
|
+
"types": "tsc -p ./tsconfig.types.json",
|
|
25
|
+
"esm": "tsc -p ./tsconfig.esm.json",
|
|
26
|
+
"cjs": "tsc -p tsconfig.cjs.json",
|
|
27
|
+
"lint": "npx eslint",
|
|
28
|
+
"test": "bunx playwright test",
|
|
29
|
+
"test:ui": "bunx playwright test --ui"
|
|
30
|
+
},
|
|
31
|
+
"peerDependencies": {
|
|
32
|
+
"react": ">=17",
|
|
33
|
+
"react-dom": ">=17",
|
|
34
|
+
"typescript": "^5.8.3"
|
|
35
|
+
},
|
|
36
|
+
"dependencies": {
|
|
37
|
+
"@surfside/ads-core-mock": "0.3.0-c5bdf731.0",
|
|
38
|
+
"@surfside/ads-core-web": "0.3.0-c5bdf731.0"
|
|
39
|
+
},
|
|
40
|
+
"devDependencies": {
|
|
41
|
+
"@playwright/test": "^1.60.0",
|
|
42
|
+
"@types/bun": "latest",
|
|
43
|
+
"@types/react": "^19.0.0",
|
|
44
|
+
"@types/react-dom": "^19.0.0",
|
|
45
|
+
"react": "^19.0.0",
|
|
46
|
+
"react-dom": "^19.0.0",
|
|
47
|
+
"typedoc": "^0.28.5"
|
|
48
|
+
}
|
|
49
|
+
}
|