ad-pull v0.2.0

中文

TeleAds SDK Integration Guide

1. Introduction

TeleAds SDK is a JavaScript library for integrating advertisements into applications. It provides a simple and easy-to-use API that helps developers quickly implement ad fetching and display functionality.

2. Installation

The npm package name for TeleAds SDK is ad-pull. You can install it using the following command:

npm install ad-pull

3. Basic Usage

3.1 Importing the SDK

import { create } from "ad-pull";

3.2 Initializing the SDK

Before using the SDK, you need to initialize it:

const ad = create({
  userId: "user123", // Current user ID
  platform: "web", // Platform, e.g., web, ios, android, etc.
  isPremium: false, // Whether the user is a premium member
});

The create method accepts a configuration object with the following parameters:

• userId: Unique identifier for the current user (required)
• platform: The current running platform (required)
• isPremium: Whether the user is a premium member (optional, default is false)

3.3 Adding Ad Placements

Use the addDid method to add ad placements:

ad.addDid([
  {
    html: "#ad-container", // DOM element or selector
    placeCode: "banner_001", // Ad placement code
    onClose: () => console.log("Ad closed"),
    onOver: () => console.log("Ad playback finished"),
    onPull: () => console.log("Ad pulling started"),
    onStart: () => console.log("Ad started"),
    onStop: () => console.log("Ad stopped"),
    onPlay: () => console.log("Ad playing"),
    onError: (err) => console.error("Ad error:", err)
  }
]);

The addDid method accepts an array of objects, each representing an ad placement with the following properties:

• html: DOM element or selector string (required)
• placeCode: Unique identifier for the ad placement (required)
• onClose: Callback function when the ad is closed (optional)
• onOver: Callback function when ad playback is completed (optional)
• onPull: Callback function when ad fetching starts (optional)
• onStart: Callback function when the ad starts playing (optional)
• onStop: Callback function when the ad stops playing (optional)
• onPlay: Callback function when the ad is playing (optional)
• onError: Callback function when an error occurs (optional)

3.4 Removing Ad Placements

Use the deleteDid method to remove ad placements:

ad.deleteDid("banner_001");

3.5 Getting Ad Placement Information

Use the getDid method to get information about a specific ad placement:

const adInfo = ad.getDid("banner_001");

3.6 Getting All Ad Placement Information

Use the getAllDid method to get information about all ad placements:

const allAds = ad.getAllDid();

4. Advanced Usage

4.1 Ad Types

TeleAds SDK supports multiple ad types, including:

• Banner ads
• Interstitial ads
• Rewarded video ads

The ad type is automatically determined by the server based on the placeCode, and does not need to be specified by the client.

4.2 Ad Lifecycle

The ad lifecycle includes the following stages:

1. Pull: Start requesting ad data
2. Start: Ad starts displaying
3. Play: Ad is playing (for video ads)
4. Stop: Ad playback is paused
5. Over: Ad playback is completed
6. Close: User closes the ad

You can listen to these events through the corresponding callback functions.

4.3 Error Handling

The SDK automatically handles common errors, such as network issues and ad loading failures. You can use the onError callback to capture and handle these errors.

5. Best Practices

1. Initialize the SDK when the application starts to ensure ad functionality is always available.
2. Set up ad placements reasonably to avoid affecting user experience.
3. Implement all callback functions for better control over ad behavior and user experience.
4. For rewarded video ads, ensure that appropriate rewards are given after users complete watching.
5. Regularly check and update the SDK to get the latest features and performance improvements.

6. Considerations

1. Ensure that correct userId and platform information is provided, as this is crucial for ad targeting and data analysis.
2. Avoid frequently adding and removing ad placements, as this may affect user experience and ad effectiveness.
3. Comply with relevant advertising policies and regulations to ensure the compliance of ad content.

7. Troubleshooting

If you encounter issues, please check the following points:

1. Ensure the SDK is correctly installed and imported.
2. Verify that the parameters for the create method are correct.
3. Check if the network connection is normal.
4. Look for any error messages in the console and handle them according to the error codes.

If the problem persists, please contact the TeleAds technical support team for assistance.

8. API Reference

For a complete API reference, please refer to the following code:

import { AdPull } from "../instance";
import { Did } from "../did/didStore";

export declare namespace AdPullNamespace {
  export type AdType = "mount" | "banner" | "insert";
  export type AdMediaType = "image" | "video";

  export interface DidOption {
    html: AddDidHTML;
    placeCode: string;
    type?: AdType;
    zIndex?: number;
    onClose?: () => void;
    onOver?: () => void;
    onPull?: () => void;
    onStart?: () => void;
    onStop?: () => void;
    onPlay?: () => void;
    onError?: (err: Error) => void;
  }

  export type AdRenderOption = {
    type: AdType;
    loop: boolean;
    adContent: AdContentRes;
    width: number;
    height: number;
    placeCode:string | number;
    zIndex: number;
    onClose: () => void;
    onOver: () => void;
    onStart: () => void;
    onStop: () => void;
    onError: (err: Error) => void;
    onView:()=>void;
    onExposure:()=>void;
    onClick:()=>void
  };

  export type AddDidHTML = string | HTMLElement;
  export type addDid = (option: DidOption[]) => void;

  export type DeleteDidHTML = (string | HTMLElement) | string[] | HTMLElement[];
  export type DeleteDid = (placeCode: string | string[]) => void;

  export type GetDidHTML = string | HTMLElement;
  export type GetDid = (placeCode: string | string[]) => Did | Did[];

  export type GetAllDid = () => Did[];

  export interface CreateOptions {
    userId: string | number;
    platform: string;
    isPremium?: boolean;
  }
  export type create = (option?: CreateOptions) => AdPull;

  export type AdContentRes = AdRequestNamespace.PullAdRes;
}

export declare namespace AdRequestNamespace {
  export interface PullAdReq {
    width: number;
    height: number;
    placeCode: any;
  }

  export interface PullAdRes {
    adH: number;
    adLink: string;
    adTypeCode: string;
    adUnitId: number;
    adW: number;
    dur: number;
    eventLink: string;
    eventType: string;
    mime: string;
    placeCode: string | number;
    ratio: string;
    skip: boolean;
    skipAfter: number;
    ssnId: string;
  }

  export enum RepoTypeEnum {
    view = 1,
    exposure = 3,
    click = 5,
  }
  export interface RepoReq {
    repoType: RepoTypeEnum;
    placeCode: string | number;
    adUnitId: string;
    ssnId: string;
    userId: string | number;
    lang: string;
    platform: string;
    country: string | null;
    isTgp: boolean;
    scrnW: number;
    scrnH: number;
    xy: string;
    timezone: number;
    loadTime: number;
    timestamp: number;
    sdkVer: string;
    sign: string;
  }
}

This defines all the types and interfaces of the SDK, which can help you better understand and use the SDK's functionality.

We hope this documentation helps you successfully integrate and use the TeleAds SDK. If you have any further questions, please feel free to ask.