AdPulse Client Integration SDK (@adpulse/sdk)

Drop one script/component. Run beautiful ads.

@adpulse/sdk is the official JavaScript and React integration library for the AdPulse self-hosted ad network management platform. It allows developers to seamlessly embed styled, responsive, and animated ad cards into React, Next.js, or vanilla HTML/JS websites.

[!TIP] Recommended: Go to vulnera.online/docs and use the SDK-based templates for more design options, custom styling parameters, and better performance.

🚀 Installation

Install the package via your preferred package manager:

npm install @adpulse/sdk
# or
yarn add @adpulse/sdk
# or
pnpm add @adpulse/sdk

⚛️ React & Next.js Usage

The package exports two React components:

• <AdSlot />: Renders standard ad cards (classic, minimal, spotlight templates).
• <AdSlotBeta />: Renders advanced animated ad cards with support for curved shapes/polygons.

1. Basic Integration

import React from 'react';
import { AdSlot } from '@adpulse/sdk';

export default function BlogPost() {
  return (
    <article>
      <h1>My Blog Post</h1>
      <p>Content goes here...</p>

      {/* Renders a standard inline ad card */}
      <AdSlot
        adId="ad_9x3kz"
        publisherKey="ap_live_pk_yourKeyHere"
        position="inline"
        theme="dark"
        accent="#22c55e"
      />
    </article>
  );
}

2. Advanced / Animated Integration

Use <AdSlotBeta /> to apply entry animations, custom border curves, and high-impact media layouts:

import React from 'react';
import { AdSlotBeta } from '@adpulse/sdk';

export default function HeroSection() {
  return (
    <div>
      <AdSlotBeta
        adId="ad_k7m2p"
        publisherKey="ap_live_pk_yourKeyHere"
        position="inline"
        template="media"
        curve={true}
        curvePath="polygon(0 0, 100% 0%, 100% 100%, 39% 100%)"
        curveWidth="200px"
        cardHeight="220px"
        animation="bounceSoft"
        theme="dark"
        accent="#f76a8a"
      />
    </div>
  );
}

🌐 Vanilla JS & Programmatic Usage

For websites not using React, you can import and initialize the script loaders programmatically:

import { initAdPulse } from '@adpulse/sdk';

// 1. Initialize and dynamically inject the script tag
initAdPulse({ apiBase: 'https://vulnera.online' });

// 2. Use window.AdPulse after script load
window.addEventListener('load', () => {
  if (window.AdPulse) {
    window.AdPulse.render('#my-custom-container', {
      adId: 'ad_9x3kz',
      position: 'inline',
      theme: 'dark',
      accent: '#22c55e'
    });
    
    // Listen to SDK events
    window.AdPulse.on('impression', (data) => console.log('Ad viewed:', data));
    window.AdPulse.on('click', (data) => console.log('Ad clicked:', data));
  }
});

⚙️ Properties Reference

The following props can be passed to <AdSlot /> and <AdSlotBeta />:

| Prop Name | Type | Required | Default | Description | |---|---|---|---|---| | adId | string | Yes | - | Copy this from Dashboard > Ads | | publisherKey | string | Yes | - | Copy this from Dashboard > Publisher Keys | | position | string | No | inline | Layout format: inline | sidebar | float | banner | overlay | | theme | string | No | dark | Visual theme: dark | light | auto | | template | string | No | classic | Card template: classic | minimal | media | spotlight | custom | | accent | string | No | #22c55e | Brand accent color used for buttons and outlines | | background | string | No | - | Overrides card background color | | textColor | string | No | - | Overrides primary text color | | animation | string | No | fadeUp | Entry transition: fadeUp | fadeIn | slideRight | slideLeft | bounceSoft | none | | cta | string | No | Learn More | Custom call-to-action button label | | ctaStyle | string | No | filled | Button design: filled | outline | link | | cardSize | string | No | standard | Card dimension scale: compact | standard | large | | radius | number | No | 12 | Corner border-radius in pixels | | closeable | boolean | No | false | Shows a dismiss "X" button | | lazy | boolean | No | true | Delay rendering until the slot is close to entering the viewport | | apiBase | string | No | https://vulnera.online | Custom deployed AdPulse server URL |

Extra props for <AdSlotBeta />

| Prop Name | Type | Required | Default | Description | |---|---|---|---|---| | curve | boolean | No | false | Enables border shape clipping for images | | curvePath | string | No | - | CSS polygon path (e.g. polygon(0 0, 100% 0%, 100% 100%, 39% 100%)) | | curveWidth | string | No | 200px | Width of the curved media element | | curveHeight | string | No | 100% | Height of the curved media element |

📄 License

MIT