ad-handler

ad-handler is a flexible and easy-to-use TypeScript library for handling Facebook Instant Games advertisements. It provides a simple interface to load and display various types of ads, including banner ads, interstitial ads, rewarded video ads, and rewarded interstitial ads.

Features

• Support for multiple ad types: Banner, Interstitial, Rewarded Video, and Rewarded Interstitial
• Flexible ad loading strategy using the Chain of Responsibility pattern
• Lifecycle hooks for ad loading and display
• Built-in error handling and retry mechanism
• Customizable debug logging
• Configurable ad priority chain

Installation

Using npm:

```bash npm install ad-handler ```

Or using yarn:

```bash yarn add ad-handler ```

Usage

Here's a comprehensive example of how to use the ad-handler:

```typescript import { InitializeAdHanlder, Config, ADType } from 'ad-handler'

const adHandler = InitializeAdHanlder({ adID: { bannerID: 'YOUR_BANNER_ID', rewardedVideoID: 'YOUR_REWARDED_VIDEO_ID', interstitialID: 'YOUR_INTERSTITIAL_ID', rewardInterstitialID: 'YOUR_REWARD_INTERSTITIAL_ID', }, debugLog: true, hooks: { onAdLoadStart: (params) => { console.log('ad_load_c', params) }, onAdLoadFailed: (params) => { console.log('ad_load_fail_c', params) }, onAdLoadSuccess: (params) => { console.log('ad_load_success_c', params) }, onAdShowSuccess: (params) => { console.log('ad_show_success_c', params) if (params.type === ADType.RewardInterstitial || params.type === ADType.RewardedVideo) { console.log('ad_impression_c_100', params) } }, onAdShowFailed: (params) => { console.log('ad_show_fail_c', params) }, onRewardUnFinished: (params) => { console.log('reward ad not completed', params) }, }, priorityChain: [ADType.Interstitial, ADType.RewardInterstitial, ADType.RewardedVideo], retryCount: 3, customErrorHandler: async (error, cb) => { console.log('Custom error handler:', error) await cb() }, })

const { showAds, preloadAds, showBanner, version } = adHandler console.log('ADHanlderDebug: version', version)

// Export functions for use in other parts of your application export { showAds, preloadAds, showBanner } ```

Usage example:

```typescript // Show an ad with custom parameters showAds({ placement: 'home' })

// Preload an ad of a specific type preloadAds({ placement: 'level_complete' }, ADType.RewardedVideo)

// Show a banner ad showBanner({ position: 'bottom' }) ```

API

InitializeAdHanlder(config: Config): ADHandlerReturnType

Initializes the ad handler and returns an object with the following methods:

| Method | Description | Parameters | Return Type | | -------------- | ------------------- | ------------------------------ | ------------------------------ | | `showAds` | Display an ad | `params: any, type?: ADType` | `Promise` | | `preloadAds` | Preload an ad | `params: any, type?: ADType` | `Promise` | | `showBanner` | Display a banner ad | `params: any` | `Promise` | | `version` | Library version | - | `string` |

Config

Configuration object with the following properties:

| Property | Type | Description | Required | | ---------------------- | ------------ | ------------------------------------------ | -------- | | `adID` | `ADID` | Object containing IDs for various ad types | Yes | | `hooks` | `ADHooks` | Lifecycle hook functions | No | | `retryCount` | `number` | Retry count for ad loading | No | | `priorityChain` | `ADType[]` | Priority chain for ad types | No | | `debugLog` | `boolean` | Enable or disable debug logging | No | | `customErrorHandler` | `Function` | Custom error handler function | No |

ADType

Enum for ad types:

| Type | Description | | ---------------------- | ----------------------------------- | | `Banner` | Banner advertisement | | `Interstitial` | Interstitial advertisement | | `RewardInterstitial` | Rewarded interstitial advertisement | | `RewardedVideo` | Rewarded video advertisement |

showAdsReturnType

Possible return values for the `showAds` function:

• `'success'`: Ad was successfully shown
• `'Ad not completed'`: User skipped the ad (for rewarded ads)
• `'fail'`: Ad failed to show

Advanced Usage

You can customize the ad loading priority and implement your own retry logic using the provided hooks and custom error handler. The library uses a Chain of Responsibility pattern, allowing for flexible ad type fallbacks.

Error Handling

The library includes built-in error handling with configurable retry counts and waiting times. You can also provide a custom error handler for more specific error management.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the ISC License.