@surfside/ads-react

v0.1.18

Published

a day ago

React components for Surfside Ads

Downloads

569

0High
0Medium
0Low

Core Library Elements

Design Architecture

The library follows a modern, modular React architecture with two primary layers:

Provider: SurfsideProvider – Initializes the Surfside Ads SDK and manages shared global context.
Hooks: Custom hooks that encapsulate ad fetching, rendering logic, state management, and analytics.

This separation of concerns allows for clean and extensible integration across a variety of use cases.

Quick Start

Installation

# Using npm
npm install @surfside/ads-react

# Using yarn
yarn add @surfside/ads-react

# Using bun
bun add @surfside/ads-react

Basic Usage

Wrap your application with SurfsideProvider to provide the necessary context.

export default function App() {
    return (
        <html lang="en">
            <head>
                {/* Head Content */}
            </head>
            <body>
                <SurfsideProvider
                    channelId='XXXXX'
                    accountId='XXXXX'
                    siteId='XXXXX'
                    locationId='surfside-nyc'
                    userId='surfside-007'
                >
                    <div>
                        {/* Application Content */}
                    </div>
                </SurfsideProvider>
            </body>
        </html>
    );
}

Render a banner ad using the useSurfsideBanner hook.

const Homepage = () => {
    const {
        banner,
        loading,
        error,
        analytics
    } = useSurfsideBanner({
        zoneId: 'XXXXX',
        size: [4,1 ]
    });

    useEffect(() => {
        analytics?.trackWin();
    }, [analytics]);

    if (loading) {
        return <BannerSkeleton/>;
    }

    if (error) {
        return <FallbackComponent/>;
    }

    return (
        <div>
            <h1>Welcome!</h1>
            <MenuBar/>
            {/* Banner Ad right below the menu bar */}
            <div dangerouslySetInnerHTML={{__html: banner.adm}}></div>
            {/* ... webpage content */}
        </div>
    );
};

Where to start

Follow these guides to set up your Surfside Ads implementation

Performance & Compatibility

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.

To avoid hydration issues, always ensure components using Surfside hooks are rendered only after the client has mounted.

const IsClientOnly = ({ children }: { children: React.ReactNode }) => {
    const [ready, setReady] = React.useState(false);
    React.useEffect(() => setReady(true), []);
    return ready ? <>{children}</> : null;
};

You can wrap Surfside components in a guard like this if needed.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme