@adtogether/web-sdk 0.1.0 → 0.1.4

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.1.1
+
+* Update repository URLs to new organization.
+* Prepare for version 0.1.1 release.
+
 ## 0.1.0
 
 * Initial release of the AdTogether Web SDK.

package/README.md

@@ -0,0 +1,147 @@
+# AdTogether Web SDK
+
+[![npm version](https://img.shields.io/npm/v/@adtogether/web-sdk)](https://www.npmjs.com/package/@adtogether/web-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+<p align="center">
+  <strong>"Show an ad, get an ad shown"</strong><br>
+  The Universal Ad Exchange & Reciprocal Marketing Platform
+</p>
+
+---
+
+**AdTogether** is an ad exchange platform designed to empower developers and creators. By participating in our network, you can engage in reciprocal marketing for your own applications while simultaneously driving traffic to your products and helping you **increase conversions**. Our core philosophy is simple: **"Show an ad, get an ad shown"**.
+
+This SDK allows web developers (React and Vanilla JS) to easily integrate AdTogether ads into their applications. By displaying ads from other community members, you earn **Ad Credits** that allow your own app's ads to be shown across the AdTogether network.
+
+### 🖼️ Visualizing the Experience
+
+| **Native Banner Ad** | **Interstitial Full-Screen** |
+|:---:|:---:|
+| ![Banner Example](../../public/ads/Banner_Example.png) | ![Interstitial Example](../../public/ads/Interstitial_Example.png) |
+| *Adaptive React Banner Component* | *Full-Screen Interstitial Experience* |
+
+## Features
+
+- 🖼️ **Banner Ads** — Native React `AdTogetherBanner` component with automatic impression tracking and dark mode support.
+- 📺 **Interstitial Ads** — Full-screen `AdTogetherInterstitial` component with a configurable close-button countdown.
+- 🌑 **Dark Mode Support** — All ad components automatically adapt to system preference, or can be set to `'dark'` / `'light'` explicitly.
+- ⚖️ **Fair Exchange** — Automated impression and click tracking ensures fair distribution of ad credits.
+- 🔌 **Easy Integration** — A single `initialize()` call and one component is all you need to start earning credits and increase conversions.
+- 🧩 **Vanilla JS Support** — Core logic decoupled for use without React or any framework.
+
+## Getting Started
+
+### 1. Install
+
+```bash
+npm install @adtogether/web-sdk
+```
+
+### 2. Initialize
+
+Call `AdTogether.initialize()` before rendering any ad components. You can obtain your App ID from the [AdTogether Dashboard](https://adtogether.relaxsoftwareapps.com/dashboard).
+
+```typescript
+import { AdTogether } from '@adtogether/web-sdk';
+
+AdTogether.initialize({ appId: 'YOUR_APP_ID' });
+```
+
+## Usage
+
+### Banner Ads
+
+Use the `AdTogetherBanner` component anywhere in your React tree. It fetches an ad, renders it, and automatically tracks impressions when 50% or more of the component is visible.
+
+```jsx
+import { AdTogetherBanner } from '@adtogether/web-sdk/react';
+
+function MyApp() {
+  return (
+    <div>
+      <h1>My Awesome Web App</h1>
+
+      <AdTogetherBanner
+        adUnitId="home_bottom_banner"
+        onAdLoaded={() => console.log('Banner loaded!')}
+        onAdFailedToLoad={(error) => console.error('Banner error:', error)}
+      />
+    </div>
+  );
+}
+```
+
+#### `AdTogetherBanner` Props
+
+| Prop               | Type                    | Default   | Description |
+|--------------------|-------------------------|-----------|-------------|
+| `adUnitId`         | `string`                | **required** | Unique identifier for this ad placement. |
+| `width`            | `number \| string`      | `'100%'`  | Width of the ad element. |
+| `height`           | `number \| string`      | `'auto'`  | Height of the ad element. |
+| `theme`            | `'dark' \| 'light' \| 'auto'` | `'auto'` | Color scheme. `'auto'` follows system preference. |
+| `onAdLoaded`       | `() => void`            | —         | Called when the ad has been successfully fetched and rendered. |
+| `onAdFailedToLoad` | `(error: Error) => void`| —         | Called if the ad fails to load. |
+| `className`        | `string`                | `''`      | Additional CSS class name for the container. |
+| `style`            | `React.CSSProperties`   | `{}`      | Additional inline styles for the container. |
+
+### Interstitial Ads
+
+Show a full-screen interstitial ad as a portal overlay. A countdown timer is displayed before the user is allowed to close the ad.
+
+```jsx
+import { useState } from 'react';
+import { AdTogetherInterstitial } from '@adtogether/web-sdk/react';
+
+function MyApp() {
+  const [showInterstitial, setShowInterstitial] = useState(false);
+
+  return (
+    <div>
+      <button onClick={() => setShowInterstitial(true)}>
+        Show Interstitial Ad
+      </button>
+
+      <AdTogetherInterstitial
+        adUnitId="level_complete_interstitial"
+        isOpen={showInterstitial}
+        onClose={() => setShowInterstitial(false)}
+        closeDelay={5}
+        onAdLoaded={() => console.log('Interstitial ready')}
+        onAdFailedToLoad={(error) => console.error('Interstitial error:', error)}
+      />
+    </div>
+  );
+}
+```
+
+#### `AdTogetherInterstitial` Props
+
+| Prop               | Type                    | Default   | Description |
+|--------------------|-------------------------|-----------|-------------|
+| `adUnitId`         | `string`                | **required** | Unique identifier for this ad placement. |
+| `isOpen`           | `boolean`               | **required** | When `true`, the interstitial is displayed. |
+| `onClose`          | `() => void`            | **required** | Called when the user closes the interstitial. |
+| `closeDelay`       | `number`                | `3`       | Seconds before the close button appears. A countdown is shown during this time. |
+| `theme`            | `'dark' \| 'light' \| 'auto'` | `'auto'` | Color scheme. `'auto'` follows system preference. |
+| `onAdLoaded`       | `() => void`            | —         | Called when the ad has been successfully fetched. |
+| `onAdFailedToLoad` | `(error: Error) => void`| —         | Called if the ad fails to load. The dialog is automatically dismissed on failure. |
+
+## How Credits Work
+
+1. **Earn credits** — Every time your app displays an ad from the AdTogether network and the impression is verified, you earn ad credits.
+2. **Spend credits** — Your ad credits are automatically spent to show *your* campaigns inside other apps on the network, helping you increase conversions.
+3. **Fair weighting** — Different ad formats and geographies have different credit weights, ensuring a level playing field for apps of all sizes.
+
+Create and manage your campaigns from the [AdTogether Dashboard](https://adtogether.relaxsoftwareapps.com/dashboard).
+
+## Additional Information
+
+- 📖 **Documentation**: [adtogether.relaxsoftwareapps.com/docs](https://adtogether.relaxsoftwareapps.com/docs)
+- 🐛 **Issues**: [GitHub Issues](https://github.com/undecided2003/AdTogether/issues)
+- 💬 **Support**: Join our [Discord community](https://discord.gg/adtogether) for real-time help.
+- 🌐 **Dashboard**: [adtogether.relaxsoftwareapps.com/dashboard](https://adtogether.relaxsoftwareapps.com/dashboard)
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

package/dist/chunk-7IJIBJD4.mjs

@@ -0,0 +1,85 @@
+// src/core/AdTogether.ts
+var AdTogether = class _AdTogether {
+  constructor() {
+    this.allowSelfAds = true;
+    this.baseUrl = "https://adtogether.relaxsoftwareapps.com";
+  }
+  static get shared() {
+    if (!_AdTogether.instance) {
+      _AdTogether.instance = new _AdTogether();
+    }
+    return _AdTogether.instance;
+  }
+  static initialize(options) {
+    const sdk = _AdTogether.shared;
+    sdk.appId = options.apiKey || options.appId;
+    if (options.allowSelfAds !== void 0) {
+      sdk.allowSelfAds = options.allowSelfAds;
+    }
+    if (options.baseUrl) {
+      sdk.baseUrl = options.baseUrl;
+    } else if (typeof window !== "undefined") {
+      sdk.baseUrl = "";
+    }
+    console.log(`AdTogether SDK Initialized with App ID: ${sdk.appId}`);
+  }
+  assertInitialized() {
+    if (!this.appId) {
+      console.error("AdTogether Error: SDK has not been initialized. Please call AdTogether.initialize() before displaying ads.");
+      return false;
+    }
+    return true;
+  }
+  static async fetchAd(adUnitId, adType) {
+    if (!_AdTogether.shared.assertInitialized()) {
+      throw new Error("AdTogether not initialized");
+    }
+    try {
+      const sdk = _AdTogether.shared;
+      let url = `${sdk.baseUrl}/api/ads/serve?country=global&adUnitId=${adUnitId}&apiKey=${sdk.appId}`;
+      if (adType) {
+        url += `&adType=${adType}`;
+      }
+      if (sdk.lastAdId) {
+        url += `&exclude=${sdk.lastAdId}`;
+      }
+      url += `&allowSelfAds=${sdk.allowSelfAds}`;
+      if (typeof window !== "undefined") {
+        url += `&sourceUrl=${encodeURIComponent(window.location.href)}`;
+      }
+      const response = await fetch(url);
+      if (response.ok) {
+        const ad = await response.json();
+        sdk.lastAdId = ad.id;
+        return ad;
+      }
+      throw new Error(`Failed to fetch ad. Status: ${response.status}`);
+    } catch (err) {
+      throw err;
+    }
+  }
+  static trackImpression(adId, token) {
+    this.trackEvent("/api/ads/impression", adId, token);
+  }
+  static trackClick(adId, token) {
+    this.trackEvent("/api/ads/click", adId, token);
+  }
+  static trackEvent(endpoint, adId, token) {
+    if (!_AdTogether.shared.assertInitialized()) return;
+    fetch(`${_AdTogether.shared.baseUrl}${endpoint}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        adId,
+        token,
+        apiKey: _AdTogether.shared.appId
+      })
+    }).catch(console.error);
+  }
+};
+
+export {
+  AdTogether
+};

package/dist/index.d.mts

@@ -1,27 +1,35 @@
+type AdType = 'banner' | 'interstitial';
 interface AdModel {
     id: string;
     title: string;
     description: string;
     clickUrl?: string;
     imageUrl?: string;
+    token?: string;
+    adType?: AdType;
 }
 interface AdTogetherOptions {
-    appId: string;
+    appId?: string;
+    apiKey?: string;
     baseUrl?: string;
+    /** Whether to show your own ads as fallback if no external ads are available. Defaults to true. */
+    allowSelfAds?: boolean;
 }
 
 declare class AdTogether {
     private static instance;
     private appId?;
+    private allowSelfAds;
     baseUrl: string;
     private constructor();
     static get shared(): AdTogether;
     static initialize(options: AdTogetherOptions): void;
     assertInitialized(): boolean;
-    static fetchAd(adUnitId: string): Promise<AdModel>;
-    static trackImpression(adId: string): void;
-    static trackClick(adId: string): void;
+    private lastAdId?;
+    static fetchAd(adUnitId: string, adType?: AdType): Promise<AdModel>;
+    static trackImpression(adId: string, token?: string): void;
+    static trackClick(adId: string, token?: string): void;
     private static trackEvent;
 }
 
-export { type AdModel, AdTogether, type AdTogetherOptions };
+export { type AdModel, AdTogether, type AdTogetherOptions, type AdType };

package/dist/index.d.ts

@@ -1,27 +1,35 @@
+type AdType = 'banner' | 'interstitial';
 interface AdModel {
     id: string;
     title: string;
     description: string;
     clickUrl?: string;
     imageUrl?: string;
+    token?: string;
+    adType?: AdType;
 }
 interface AdTogetherOptions {
-    appId: string;
+    appId?: string;
+    apiKey?: string;
     baseUrl?: string;
+    /** Whether to show your own ads as fallback if no external ads are available. Defaults to true. */
+    allowSelfAds?: boolean;
 }
 
 declare class AdTogether {
     private static instance;
     private appId?;
+    private allowSelfAds;
     baseUrl: string;
     private constructor();
     static get shared(): AdTogether;
     static initialize(options: AdTogetherOptions): void;
     assertInitialized(): boolean;
-    static fetchAd(adUnitId: string): Promise<AdModel>;
-    static trackImpression(adId: string): void;
-    static trackClick(adId: string): void;
+    private lastAdId?;
+    static fetchAd(adUnitId: string, adType?: AdType): Promise<AdModel>;
+    static trackImpression(adId: string, token?: string): void;
+    static trackClick(adId: string, token?: string): void;
     private static trackEvent;
 }
 
-export { type AdModel, AdTogether, type AdTogetherOptions };
+export { type AdModel, AdTogether, type AdTogetherOptions, type AdType };

package/dist/index.js

@@ -27,7 +27,8 @@ module.exports = __toCommonJS(index_exports);
 // src/core/AdTogether.ts
 var AdTogether = class _AdTogether {
   constructor() {
-    this.baseUrl = "https://adtogether.com";
+    this.allowSelfAds = true;
+    this.baseUrl = "https://adtogether.relaxsoftwareapps.com";
   }
   static get shared() {
     if (!_AdTogether.instance) {
@@ -37,11 +38,16 @@ var AdTogether = class _AdTogether {
   }
   static initialize(options) {
     const sdk = _AdTogether.shared;
-    sdk.appId = options.appId;
+    sdk.appId = options.apiKey || options.appId;
+    if (options.allowSelfAds !== void 0) {
+      sdk.allowSelfAds = options.allowSelfAds;
+    }
     if (options.baseUrl) {
       sdk.baseUrl = options.baseUrl;
+    } else if (typeof window !== "undefined") {
+      sdk.baseUrl = "";
     }
-    console.log(`AdTogether SDK Initialized with App ID: ${options.appId}`);
+    console.log(`AdTogether SDK Initialized with App ID: ${sdk.appId}`);
   }
   assertInitialized() {
     if (!this.appId) {
@@ -50,30 +56,52 @@ var AdTogether = class _AdTogether {
     }
     return true;
   }
-  static async fetchAd(adUnitId) {
+  static async fetchAd(adUnitId, adType) {
     if (!_AdTogether.shared.assertInitialized()) {
       throw new Error("AdTogether not initialized");
     }
-    const response = await fetch(`${_AdTogether.shared.baseUrl}/api/ads/serve?country=global&adUnitId=${adUnitId}`);
-    if (!response.ok) {
+    try {
+      const sdk = _AdTogether.shared;
+      let url = `${sdk.baseUrl}/api/ads/serve?country=global&adUnitId=${adUnitId}&apiKey=${sdk.appId}`;
+      if (adType) {
+        url += `&adType=${adType}`;
+      }
+      if (sdk.lastAdId) {
+        url += `&exclude=${sdk.lastAdId}`;
+      }
+      url += `&allowSelfAds=${sdk.allowSelfAds}`;
+      if (typeof window !== "undefined") {
+        url += `&sourceUrl=${encodeURIComponent(window.location.href)}`;
+      }
+      const response = await fetch(url);
+      if (response.ok) {
+        const ad = await response.json();
+        sdk.lastAdId = ad.id;
+        return ad;
+      }
       throw new Error(`Failed to fetch ad. Status: ${response.status}`);
+    } catch (err) {
+      throw err;
     }
-    return response.json();
   }
-  static trackImpression(adId) {
-    this.trackEvent("/api/ads/impression", adId);
+  static trackImpression(adId, token) {
+    this.trackEvent("/api/ads/impression", adId, token);
   }
-  static trackClick(adId) {
-    this.trackEvent("/api/ads/click", adId);
+  static trackClick(adId, token) {
+    this.trackEvent("/api/ads/click", adId, token);
   }
-  static trackEvent(endpoint, adId) {
+  static trackEvent(endpoint, adId, token) {
     if (!_AdTogether.shared.assertInitialized()) return;
     fetch(`${_AdTogether.shared.baseUrl}${endpoint}`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json"
       },
-      body: JSON.stringify({ adId })
+      body: JSON.stringify({
+        adId,
+        token,
+        apiKey: _AdTogether.shared.appId
+      })
     }).catch(console.error);
   }
 };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import {
   AdTogether
-} from "./chunk-IDJUJZAL.mjs";
+} from "./chunk-7IJIBJD4.mjs";
 export {
   AdTogether
 };

package/dist/react/index.d.mts

@@ -15,4 +15,21 @@ interface AdTogetherBannerProps {
 }
 declare const AdTogetherBanner: React.FC<AdTogetherBannerProps>;
 
-export { AdTogetherBanner, type AdTogetherBannerProps };
+interface AdTogetherInterstitialProps {
+    adUnitId: string;
+    /** When true, the interstitial is shown (fetches and displays full-screen ad) */
+    isOpen: boolean;
+    /** Called when the user closes the interstitial */
+    onClose: () => void;
+    /** Called when the ad is successfully loaded */
+    onAdLoaded?: () => void;
+    /** Called when the ad fails to load */
+    onAdFailedToLoad?: (error: Error) => void;
+    /** Pass 'dark' to use dark mode, 'light' for light mode, or 'auto' (default) to respect system preference */
+    theme?: 'dark' | 'light' | 'auto';
+    /** Delay in seconds before the close button appears. Defaults to 3 */
+    closeDelay?: number;
+}
+declare const AdTogetherInterstitial: React.FC<AdTogetherInterstitialProps>;
+
+export { AdTogetherBanner, type AdTogetherBannerProps, AdTogetherInterstitial, type AdTogetherInterstitialProps };

package/dist/react/index.d.ts

@@ -15,4 +15,21 @@ interface AdTogetherBannerProps {
 }
 declare const AdTogetherBanner: React.FC<AdTogetherBannerProps>;
 
-export { AdTogetherBanner, type AdTogetherBannerProps };
+interface AdTogetherInterstitialProps {
+    adUnitId: string;
+    /** When true, the interstitial is shown (fetches and displays full-screen ad) */
+    isOpen: boolean;
+    /** Called when the user closes the interstitial */
+    onClose: () => void;
+    /** Called when the ad is successfully loaded */
+    onAdLoaded?: () => void;
+    /** Called when the ad fails to load */
+    onAdFailedToLoad?: (error: Error) => void;
+    /** Pass 'dark' to use dark mode, 'light' for light mode, or 'auto' (default) to respect system preference */
+    theme?: 'dark' | 'light' | 'auto';
+    /** Delay in seconds before the close button appears. Defaults to 3 */
+    closeDelay?: number;
+}
+declare const AdTogetherInterstitial: React.FC<AdTogetherInterstitialProps>;
+
+export { AdTogetherBanner, type AdTogetherBannerProps, AdTogetherInterstitial, type AdTogetherInterstitialProps };