@surfside/ads-react 0.1.21 → 0.1.23
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 +1 -1
- package/lib/cjs/BuildInfo.js.map +1 -1
- package/lib/cjs/utils/useLog.js +8 -0
- package/lib/cjs/utils/useLog.js.map +1 -0
- package/lib/esm/BuildInfo.js +1 -1
- package/lib/esm/BuildInfo.js.map +1 -1
- package/lib/esm/utils/useLog.js +4 -0
- package/lib/esm/utils/useLog.js.map +1 -0
- package/lib/types/utils/useLog.d.ts +2 -0
- package/package.json +44 -44
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
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.SurfsideAdReactVersionInfo = void 0;
|
|
4
|
-
exports.SurfsideAdReactVersionInfo = { buildBranch: '
|
|
4
|
+
exports.SurfsideAdReactVersionInfo = { buildBranch: 'hotfix-0.1.23', buildHash: 'f4f4536', buildVer: '0.1.23' };
|
|
5
5
|
//# sourceMappingURL=BuildInfo.js.map
|
package/lib/cjs/BuildInfo.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"BuildInfo.js","sourceRoot":"src/","sources":["BuildInfo.ts"],"names":[],"mappings":";;;AAAa,QAAA,0BAA0B,GAAG,EAAE,WAAW,EAAE,
|
|
1
|
+
{"version":3,"file":"BuildInfo.js","sourceRoot":"src/","sources":["BuildInfo.ts"],"names":[],"mappings":";;;AAAa,QAAA,0BAA0B,GAAG,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAC,CAAC"}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.useLog = void 0;
|
|
4
|
+
const ads_core_1 = require("@surfside/ads-core");
|
|
5
|
+
const react_1 = require("react");
|
|
6
|
+
const useLog = (logger, context) => (0, react_1.useMemo)(() => (0, ads_core_1.Ctx)(logger)?.with(context), [logger, context]);
|
|
7
|
+
exports.useLog = useLog;
|
|
8
|
+
//# sourceMappingURL=useLog.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"useLog.js","sourceRoot":"../@surfside-ads-react/","sources":["utils/useLog.ts"],"names":[],"mappings":";;;AAAA,iDAAuD;AACvD,iCAAgC;AAEzB,MAAM,MAAM,GAAG,CAAC,MAA2B,EAAE,OAAe,EAAE,EAAE,CACnE,IAAA,eAAO,EACH,GAAG,EAAE,CAAC,IAAA,cAAG,EAAC,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,EAChC,CAAC,MAAM,EAAE,OAAO,CAAC,CACpB,CAAC;AAJO,QAAA,MAAM,UAIb"}
|
package/lib/esm/BuildInfo.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export const SurfsideAdReactVersionInfo = { buildBranch: '
|
|
1
|
+
export const SurfsideAdReactVersionInfo = { buildBranch: 'hotfix-0.1.23', buildHash: 'f4f4536', buildVer: '0.1.23' };
|
|
2
2
|
//# sourceMappingURL=BuildInfo.js.map
|
package/lib/esm/BuildInfo.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"BuildInfo.js","sourceRoot":"src/","sources":["BuildInfo.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,WAAW,EAAE,
|
|
1
|
+
{"version":3,"file":"BuildInfo.js","sourceRoot":"src/","sources":["BuildInfo.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAC,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"useLog.js","sourceRoot":"../@surfside-ads-react/","sources":["utils/useLog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAgB,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAEhC,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,MAA2B,EAAE,OAAe,EAAE,EAAE,CACnE,OAAO,CACH,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,EAChC,CAAC,MAAM,EAAE,OAAO,CAAC,CACpB,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,44 +1,44 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@surfside/ads-react",
|
|
3
|
-
"version": "0.1.
|
|
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
|
-
"prebuild": "echo \"export const SurfsideAdReactVersionInfo = { buildBranch: '$(git rev-parse --abbrev-ref HEAD)', buildHash: '$(git rev-parse --short HEAD)', buildVer: '$(bun -e 'console.log(require(\"./package.json\").version)')'};\" > src/BuildInfo.ts",
|
|
24
|
-
"build": "
|
|
25
|
-
"types": "tsc -p ./tsconfig.types.json",
|
|
26
|
-
"esm": "tsc -p ./tsconfig.esm.json",
|
|
27
|
-
"cjs": "tsc -p tsconfig.cjs.json",
|
|
28
|
-
"lint": "npx eslint"
|
|
29
|
-
},
|
|
30
|
-
"peerDependencies": {
|
|
31
|
-
"react": ">=17",
|
|
32
|
-
"typescript": "^5.8.3"
|
|
33
|
-
},
|
|
34
|
-
"dependencies": {
|
|
35
|
-
"@surfside/ads-core-web": "
|
|
36
|
-
"@surfside/ads-core-mock": "
|
|
37
|
-
},
|
|
38
|
-
"devDependencies": {
|
|
39
|
-
"@types/bun": "latest",
|
|
40
|
-
"@types/react": "^18.0.0",
|
|
41
|
-
"@types/react-dom": "^18.0.0",
|
|
42
|
-
"typedoc": "^0.28.5"
|
|
43
|
-
}
|
|
44
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@surfside/ads-react",
|
|
3
|
+
"version": "0.1.23",
|
|
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
|
+
"prebuild": "echo \"export const SurfsideAdReactVersionInfo = { buildBranch: '$(git rev-parse --abbrev-ref HEAD)', buildHash: '$(git rev-parse --short HEAD)', buildVer: '$(bun -e 'console.log(require(\"./package.json\").version)')'};\" > src/BuildInfo.ts",
|
|
24
|
+
"build": "bun x npm-run-all --parallel \"types\" \"esm\" \"cjs\"",
|
|
25
|
+
"types": "tsc -p ./tsconfig.types.json",
|
|
26
|
+
"esm": "tsc -p ./tsconfig.esm.json",
|
|
27
|
+
"cjs": "tsc -p tsconfig.cjs.json",
|
|
28
|
+
"lint": "npx eslint"
|
|
29
|
+
},
|
|
30
|
+
"peerDependencies": {
|
|
31
|
+
"react": ">=17",
|
|
32
|
+
"typescript": "^5.8.3"
|
|
33
|
+
},
|
|
34
|
+
"dependencies": {
|
|
35
|
+
"@surfside/ads-core-web": "0.1.23",
|
|
36
|
+
"@surfside/ads-core-mock": "0.1.23"
|
|
37
|
+
},
|
|
38
|
+
"devDependencies": {
|
|
39
|
+
"@types/bun": "latest",
|
|
40
|
+
"@types/react": "^18.0.0",
|
|
41
|
+
"@types/react-dom": "^18.0.0",
|
|
42
|
+
"typedoc": "^0.28.5"
|
|
43
|
+
}
|
|
44
|
+
}
|