@adsgram/react 1.0.0

package/README.md

@@ -0,0 +1,99 @@
+# @adsgram/react
+
+React bindings for Adsgram SDK. Provides components and hooks for ad tasks and fullscreen banners.
+
+## Installation
+
+```bash
+npm install @adsgram/react
+# or
+yarn add @adsgram/react
+# or
+pnpm add @adsgram/react
+```
+
+## Components
+
+### `<AdsgramTask />`
+
+React component for the `<adsgram-task>` custom element.
+
+#### Props
+
+| Prop               | Type           | Description                             |
+|--------------------|----------------|-----------------------------------------|
+| `blockId`          | `string`       | Unique task block ID (required)         |
+| `debug`            | `boolean`      | Enable debug mode (optional)            |
+| `className`        | `string`       | Optional CSS class name (optional)      |
+| `onReward`         | `EventHandler` | Reward event callback (optional)        |
+| `onError`          | `EventHandler` | Error event callback (optional)         |
+| `onBannerNotFound` | `EventHandler` | No banner available callback (optional) |
+| `onTooLongSession` | `EventHandler` | Long session callback (optional)        |
+
+#### Example
+
+```tsx
+import { AdsgramTask } from '@adsgram/react';
+
+const handleReward = () => {
+  // your code to reward user
+};
+
+const handleError = () => {
+  // do nothing or handle error
+};
+
+function MyTask() {
+  return (
+    <AdsgramTask blockId="task-123" className={styles.task} onReward={handleReward} onError={handleError}>
+      <span slot="reward" className={styles.task__reward}>1000 coins</span>
+      <div slot="button" className={styles.task__button}>go</div>
+      <div slot="claim" className={stylestask__button_claim}>claim</div>
+      <div slot="done" className={stylestask__button_done}>done</div>
+    </AdsgramTask>
+  );
+}
+```
+
+### Hook
+
+### `useAdsgram`
+
+#### Props
+
+| Prop               | Type                           | Description                                       |
+| ------------------ | ------------------------------ | ------------------------------------------------- |
+| `blockId`          | `string`                       | Unique ad block ID (required)                     |
+| `debug`            | `boolean`                      | Enable debug mode (optional)                      |
+| `debugBannerType`  | `string`                       | Forced banner type in debug mode (optional)       |
+| `onReward`         | `(event: CustomEvent) => void` | Handler for the `reward` event (optional)         |
+| `onError`          | `(event: CustomEvent) => void` | Handler for the `error` event (optional)          |
+
+#### Returns
+An object with methods to control the Adsgram ad:
+- `show(): Promise<ShowPromiseResult>` — Shows the ad and resolves with the result.
+- `addEventListener(event: string, handler: (event: CustomEvent) => void): void` — Add event listener.
+- `removeEventListener(event: string, handler: (event: CustomEvent) => void): void` — Remove event listener.
+- `destroy(): void` — Destroys the ad controller.
+
+#### Example
+
+```tsx
+import { useAdsgram } from '@adsgram/react';
+
+function MyAdButton() {
+  const handleReward = () => {
+    // user watch ad till the end
+    // your code to reward user for rewarded format
+  }
+
+  const handleError = () => {
+    // user get error during playing ad
+    // do nothing or whatever you want
+  },
+
+  const { show } = useAdsgram({ blockId: 'task-123', onReward: handleReward, onError: handleError });
+
+  return <button onClick={show}>Show Ad</button>;
+}
+```

package/dist/components/adsgramTask.d.ts

@@ -0,0 +1,70 @@
+import { BlockId, EventHandler } from "@adsgram/common";
+import React, { JSX } from "react";
+/**
+ * Props for the AdsgramTask component
+ * @interface TaskProps
+ * @property {BlockId} blockId - The unique identifier for the task block
+ * @property {boolean} [debug] - Whether to enable debug mode
+ * @property {string} [className] - Additional CSS class names
+ * @property {React.ReactNode} [children] - Child elements to render inside the task component
+ * @property {EventHandler} [onReward] - Callback for reward events
+ * @property {EventHandler} [onBannerNotFound] - Callback for banner not found events
+ * @property {EventHandler} [onTooLongSession] - Callback for too long session events
+ * @property {EventHandler} [onError] - Callback for error events
+ */
+export interface TaskProps {
+    blockId: BlockId;
+    debug?: boolean;
+    className?: string;
+    children?: React.ReactNode;
+    onReward?: EventHandler;
+    onBannerNotFound?: EventHandler;
+    onTooLongSession?: EventHandler;
+    onError?: EventHandler;
+}
+/**
+ * A React component wrapper for the Adsgram Task custom element.
+ * Handles initialization and event binding for the Adsgram task functionality.
+ *
+ * @component
+ * @param {TaskProps} props - Component properties
+ * @returns {JSX.Element | null} The rendered task element or null if not ready
+ *
+ * @example
+ * ```tsx
+ * import { AdsgramTask } from "@adsgram/react";
+ *
+ * function Task() {
+ *   const handleReward = (event: CustomEvent<string>) => {
+ *     console.log("User earned reward:", event.detail);
+ *   };
+ *
+ *   const handleError = (event: CustomEvent<string>) => {
+ *     console.error("Task error:", event.detail);
+ *   };
+ *
+ *   return (
+ *     <AdsgramTask
+ *       blockId="task-123"
+ *       className={styles.task}
+ *       onReward={handleReward}
+ *       onError={handleError}
+ *     >
+ *       <span slot="reward" className={styles.task__reward}>
+ *         1000 coins
+ *       </span>
+ *       <div slot="button" className={styles.task__button}>
+ *         go
+ *       </div>
+ *       <div slot="claim" className={styles.button_claim}>
+ *         claim
+ *       </div>
+ *       <div slot="done" className={styles.task__button_done}>
+ *         done
+ *       </div>
+ *     </AdsgramTask>
+ *   );
+ * }
+ * ```
+ */
+export declare const AdsgramTask: ({ blockId, debug, className, onReward, onBannerNotFound, onTooLongSession, onError, children, }: TaskProps) => JSX.Element | null;

package/dist/components/adsgramTask.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { getObjectKeys, } from "@adsgram/common";
+import { useEffect, useRef, useState } from "react";
+/**
+ * A React component wrapper for the Adsgram Task custom element.
+ * Handles initialization and event binding for the Adsgram task functionality.
+ *
+ * @component
+ * @param {TaskProps} props - Component properties
+ * @returns {JSX.Element | null} The rendered task element or null if not ready
+ *
+ * @example
+ * ```tsx
+ * import { AdsgramTask } from "@adsgram/react";
+ *
+ * function Task() {
+ *   const handleReward = (event: CustomEvent<string>) => {
+ *     console.log("User earned reward:", event.detail);
+ *   };
+ *
+ *   const handleError = (event: CustomEvent<string>) => {
+ *     console.error("Task error:", event.detail);
+ *   };
+ *
+ *   return (
+ *     <AdsgramTask
+ *       blockId="task-123"
+ *       className={styles.task}
+ *       onReward={handleReward}
+ *       onError={handleError}
+ *     >
+ *       <span slot="reward" className={styles.task__reward}>
+ *         1000 coins
+ *       </span>
+ *       <div slot="button" className={styles.task__button}>
+ *         go
+ *       </div>
+ *       <div slot="claim" className={styles.button_claim}>
+ *         claim
+ *       </div>
+ *       <div slot="done" className={styles.task__button_done}>
+ *         done
+ *       </div>
+ *     </AdsgramTask>
+ *   );
+ * }
+ * ```
+ */
+export const AdsgramTask = ({ blockId, debug, className, onReward, onBannerNotFound, onTooLongSession, onError, children, }) => {
+    const taskRef = useRef(null);
+    const [ready, setReady] = useState(false);
+    // Wait for custom element to be defined
+    useEffect(() => {
+        customElements.whenDefined("adsgram-task").then(() => {
+            setReady(true);
+        });
+    }, []);
+    // Setup and cleanup event listeners
+    useEffect(() => {
+        const task = taskRef.current;
+        if (!task || !ready)
+            return;
+        const eventMap = {
+            reward: onReward,
+            onBannerNotFound: onBannerNotFound,
+            onTooLongSession: onTooLongSession,
+            onError: onError,
+        };
+        getObjectKeys(eventMap).forEach((eventName) => {
+            const handler = eventMap[eventName];
+            if (handler) {
+                task.addEventListener(eventName, handler);
+            }
+        });
+        return () => {
+            getObjectKeys(eventMap).forEach((eventName) => {
+                const handler = eventMap[eventName];
+                if (handler) {
+                    task.removeEventListener(eventName, handler);
+                }
+            });
+        };
+    }, [onReward, onBannerNotFound, onTooLongSession, onError, ready]);
+    // Don't render until custom element is ready
+    if (!ready)
+        return null;
+    return (_jsx("adsgram-task", { ref: taskRef, "data-debug": debug ?? false, "data-block-id": blockId, className: className, children: children }));
+};

package/dist/hooks/useAdsgram.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A custom React hook for integrating with Adsgram ad service.
+ * Provides methods to show ads, manage event listeners, and clean up resources.
+ *
+ * @module useAdsgram
+ * @param {AdsgramProps} props - Initialization parameters for Adsgram
+ * @returns {AdsgramMethods} An object containing methods to interact with Adsgram
+ *
+ */
+import type { AdsgramMethods, AdsgramProps } from "@adsgram/common";
+/**
+ * React hook for managing Adsgram ad integration
+ * @param {AdsgramProps} props - Configuration parameters for Adsgram initialization
+ * @returns {AdsgramMethods} Methods to interact with the Adsgram sdk
+ * @param {string} params.blockId - Unique identifier for the ad block
+ * @param {boolean} [params.debug=false] - Enable debug mode
+ * @param {BannerType} [params.debugBannerType] - Forced banner type in debug mode
+ * @param {HandlerType} [params.onReward] - Callback when user completes a rewarded ad
+ * @param {HandlerType} [params.onError] - Callback when ad playback fails
+ *
+ * @example
+ * basic usage example
+ * ```tsx
+ * import { useAdsgram } from "@adsgram/react";
+ *
+ * function MyComponent() {
+ *   const { show } = useAdsgram({
+ *     blockId: "123",
+ *     onReward: () => {
+ *       // user watch ad till the end
+ *       // your code to reward user for rewarded format
+ *     },
+ *     onError: () => {
+ *       // user get error during playing ad
+ *       // do nothing or whatever you want
+ *     },
+ *   });
+ *
+ *   return (
+ *     <button onClick={show}>Show Ad</button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useAdsgram({ blockId, debug, debugBannerType, onReward, onError, }: AdsgramProps): AdsgramMethods;

package/dist/hooks/useAdsgram.js

@@ -0,0 +1,99 @@
+import { loadScript, prepareInitParams } from "@adsgram/common";
+import { useCallback, useEffect, useRef } from "react";
+/**
+ * React hook for managing Adsgram ad integration
+ * @param {AdsgramProps} props - Configuration parameters for Adsgram initialization
+ * @returns {AdsgramMethods} Methods to interact with the Adsgram sdk
+ * @param {string} params.blockId - Unique identifier for the ad block
+ * @param {boolean} [params.debug=false] - Enable debug mode
+ * @param {BannerType} [params.debugBannerType] - Forced banner type in debug mode
+ * @param {HandlerType} [params.onReward] - Callback when user completes a rewarded ad
+ * @param {HandlerType} [params.onError] - Callback when ad playback fails
+ *
+ * @example
+ * basic usage example
+ * ```tsx
+ * import { useAdsgram } from "@adsgram/react";
+ *
+ * function MyComponent() {
+ *   const { show } = useAdsgram({
+ *     blockId: "123",
+ *     onReward: () => {
+ *       // user watch ad till the end
+ *       // your code to reward user for rewarded format
+ *     },
+ *     onError: () => {
+ *       // user get error during playing ad
+ *       // do nothing or whatever you want
+ *     },
+ *   });
+ *
+ *   return (
+ *     <button onClick={show}>Show Ad</button>
+ *   );
+ * }
+ * ```
+ */
+export function useAdsgram({ blockId, debug, debugBannerType, onReward, onError, }) {
+    const adController = useRef(null);
+    const initPromise = useRef(null);
+    const ensureInitialized = useCallback(async () => {
+        if (adController.current)
+            return adController.current;
+        if (initPromise.current)
+            return initPromise.current.then(() => {
+                if (!adController.current) {
+                    throw new Error("Adsgram controller failed to initialize.");
+                }
+                return adController.current;
+            });
+        initPromise.current = loadScript().then(() => {
+            const initParams = prepareInitParams({ blockId, debug, debugBannerType });
+            if (!window.Adsgram) {
+                throw new Error("Adsgram is not available on the window object.");
+            }
+            adController.current = window.Adsgram.init(initParams);
+            if (onReward) {
+                adController.current.addEventListener("onReward", onReward);
+            }
+            if (onError) {
+                adController.current.addEventListener("onError", onError);
+            }
+        });
+        await initPromise.current;
+        if (!adController.current) {
+            throw new Error("Adsgram controller failed to initialize.");
+        }
+        return adController.current;
+    }, [blockId, debug, debugBannerType, onError, onReward]);
+    useEffect(() => {
+        ensureInitialized();
+        return () => {
+            const controller = adController.current;
+            if (!controller)
+                return;
+            controller.destroy();
+            if (onReward)
+                controller.removeEventListener("onReward", onReward);
+            if (onError)
+                controller.removeEventListener("onError", onError);
+        };
+    }, [ensureInitialized, onError, onReward]);
+    return {
+        show: async () => {
+            const controller = await ensureInitialized();
+            return controller.show();
+        },
+        addEventListener: (event, handler) => {
+            ensureInitialized().then((controller) => {
+                controller.addEventListener(event, handler);
+            });
+        },
+        removeEventListener: (event, handler) => {
+            adController.current?.removeEventListener(event, handler);
+        },
+        destroy: () => {
+            adController.current?.destroy();
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { AdsgramTask } from "./components/adsgramTask";
+export { useAdsgram } from "./hooks/useAdsgram";
+export * from "./types/task";

package/dist/index.js

@@ -0,0 +1,5 @@
+import { loadScript } from "@adsgram/common";
+loadScript();
+export { AdsgramTask } from "./components/adsgramTask";
+export { useAdsgram } from "./hooks/useAdsgram";
+export * from "./types/task";

package/dist/types/task.d.ts

@@ -0,0 +1,15 @@
+import { AdsgramTaskElement } from "@adsgram/common";
+declare global {
+    namespace JSX {
+        interface IntrinsicElements {
+            "adsgram-task": React.DetailedHTMLProps<React.HTMLAttributes<AdsgramTaskElement>, AdsgramTaskElement>;
+        }
+    }
+}
+declare module "react" {
+    namespace JSX {
+        interface IntrinsicElements {
+            "adsgram-task": React.DetailedHTMLProps<React.HTMLAttributes<AdsgramTaskElement>, AdsgramTaskElement>;
+        }
+    }
+}

package/dist/types/task.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@adsgram/react",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@adsgram/common": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.1",
+    "@types/react": "^19.1.6",
+    "react": "^19.1.0",
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "pnpm clean && tsc",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
+  }
+}