Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/potatojam/defold-ads-wrapper

Universal wrapper for ADS on different platforms
https://github.com/potatojam/defold-ads-wrapper
admob ads defold defold-library defold-module poki unityads yandex-games
Last synced: about 1 month ago
JSON representation
Universal wrapper for ADS on different platforms
Host: GitHub
URL: https://github.com/potatojam/defold-ads-wrapper
Owner: potatojam
License: mit
Created: 2022-01-10T17:46:51.000Z (almost 3 years ago)
Default Branch: main
Last Pushed: 2023-08-01T17:34:49.000Z (over 1 year ago)
Last Synced: 2024-11-02T14:33:46.495Z (about 2 months ago)
Topics: admob, ads, defold, defold-library, defold-module, poki, unityads, yandex-games
Language: Lua
Homepage:
Size: 350 KB
Stars: 17
Watchers: 2
Forks: 1
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

awesome-defold - AdsWrapper
README

        ![](docs/ads_wrapper.png)

# Ads Wrapper for Defold

Ads Wrapper allows:

* Use the same interface for working with different advertising services.

* Advertising mediation - allows you to show ads from different sources.

Supported services: 

* Admob

* Unity Ads

* Poki

* Yandex

* Yandex Mobile Ads

* Vk Bridge

* Applovin Max

* GameDistribution

* IronSource

Ads Wrapper also allows you to run multiple networks at the same time. For example Admob and Unity Ads.

You can find more information on the [networks](#networks)

## Installation

You can use it in your own project by adding this project as a [Defold library dependency](http://www.defold.com/manuals/libraries/). Open your `game.project` file and in the dependencies field add **a link to the ZIP file of a [specific release](https://github.com/potatojam/defold-ads-wrapper/tags).**

## Initialization

First you need to make a require for `ads_wrapper.ads_wrapper` and `ads_wrapper.events`.

```lua

local ads_wrapper = require("ads_wrapper.ads_wrapper")

local events = require("ads_wrapper.events")

```

Next, you need to register the networks. More details about networks can be found [here](#networks).

```lua

-- Getting our module with networks

local test = require("ads_wrapper.ads_networks.test")

-- Register the first network

local test_1_id = ads_wrapper.register_network(test.network1, {param = "test_param 1"})

-- Register the second network

local test_2_id = ads_wrapper.register_network(test.network2, {param = "test_param 2"})

```

Next, you need to configure the mediators you need. 

There are two types: Video and Banner.

Video mediator refers to the functions associated with interstitials and rewarded videos.

Banner mediator refers to the functions associated with banners.

You need to set up only the mediator that you need. For example, Poki does not support banners.

```lua

-- Setup video mediator

ads_wrapper.setup_video({{id = test_2_id, count = 2}, {id = test_1_id, count = 2}}, 4)

-- Setup banner mediator

ads_wrapper.setup_banner({{id = test_1_id, count = 1}})

```

You can read more about mediators [here](#mediators).

Next, you need to initialize ads wrapper.

```lua

ads_wrapper.init(true, true, function(response)

    if response.result == events.SUCCESS then

        pprint("Ads wrapper is initialized", response)

    else

        pprint("Something bad happened", response)

    end

end)

```

In the first two parameters, you can specify the need to initialize the network.

First - `initilize_video`, Second - `initilize_banner`. This may take time depending on the service. 

Further, they can be initialized separately, if not done immediately.

When an advertisement is called, they will be initialized `automatically` if it has not been done before.

Almost all functions have a `callback` parameter.

`callback` - function which takes one `response` parameter.

## Response

The `response` can be of two types: `success` and `error`.

Response is a table:

* result hash _required_ May be `events.SUCCESS` or `events.ERROR`

* name string _optional_ Network name

* message string _optional_ Additional information. For example, consists info about error or it may report that the network has already been initialized when `init_video_networks` is called again.

* code hash _optional_ [Response code](#response-codes). Information that convient to track by code.

* responses table _optional_ Contains all responses if the function is called for multiple networks. This may be during initialization.

* was_open table _optional_ Some networks report whether ads was open when calling `show_interstitial` or `show_rewarded`.

Also, the response may contain additional information from a specific network.

Module `ads_wrapper.events` contains useful variables:

* `events.SUCCESS` hash("SUCCESS")

* `events.ERROR` hash("ERROR")

## Response Codes

The response table may have the code. All of them are contained in the `ads_wrapper.events` module, like `events.C_SKIPPED`. There are types of codes:

* `events.C_SKIPPED` hash("C_SKIPPED") - if the rewarded advertisement was skipped

* `events.C_ERROR_UNKNOWN` hash("C_ERROR_UNKNOWN") - an unknown error type is occured

* `events.C_ERROR_AD_BLOCK` hash("C_ERROR_AD_BLOCK") - an error is related to the adblock

* `events.C_ERROR_NO_CONNECTION` hash("C_ERROR_NO_CONNECTION") - no internet connection

## Mediators

Mediators are configured with two functions: `ads_wrapper.setup_video` and `ads_wrapper.setup_banner`.

The function sets the order which creates the queue.

Options:

* order table _required_ Ad display order. This is an array that contains objects like `{id = network_id, count = 2}`.

  * id number _required_ Id that you get when registering a network using `ads_wrapper.register_network`.

  * count number _optional_ how many times you need to show ads in a row in a queue. Default `1`

* repeat_cut number _optional_ specified if after the first cycle in queue it is necessary to cut off a part of the order. Default: the total number of all networks. Below are examples.

Examples:

1. Single network

    All other parameters are not needed for one network.

    ```lua

    ads_wrapper.setup_video({{id = test_id_1}})

    ```

    Queue: `test_1->test_1->test_1->test_1->test_1->`

2. Multiple networks with `repeat_cut` parameter

    ```lua

    ads_wrapper.setup_video({{id = test_id_1, count = 2}, {id = test_id_2, count = 2}, {id = test_id_1, count = 1}}, 3)

    ```

    Queue:

    - `1: test_1->test_1->test_2->test_2->test_1->`

    - `2: test_2->test_2->test_1->`

    - `3: test_2->test_2->test_1->`

    - And so on

    Part of the order is cut off after the first cycle.

3. Multiple networks without `repeat_cut` parameter

   `repeat_cut` automatically becomes `3`.

    ```lua

    ads_wrapper.setup_video({{id = test_id_1, count = 1}, {id = test_id_2, count = 2}})

    ```

    Queue:

    - `1: test_1->test_2->test_2->`

    - `2: test_1->test_2->test_2->`

    - `3: test_1->test_2->test_2->`

    - And so on

## Lua API

In many functions there is a queue of calls. Before calling `show_intertitial` `ads_wrapper` will check if the ad has been loaded, and if not, it will load it first. If there is an error somewhere, the queue will break.

### `ads_wrapper.register_network(network, params)`

Registers network. Returns id.

**Parameters**

- `network` table _required_ network module

- `params` table _required_ network options. They are different for every network. They can be found in the [networks](#networks) section.

**Return**

- id number Network id. It is needed to set up the mediator.

### `ads_wrapper.setup_video(order, repeat_count)`

Setups interstitial and reward mediator. More info [here](#mediators).

**Parameters**

- order table _required_ Ad display order. This is an array that contains objects like `{id = network_id, count = 2}`.

- repeat_cut number _optional_ specified if after the first cycle in queue it is necessary to cut off a part of the order. Default: the total number of all networks.

### `ads_wrapper.setup_banner(order, repeat_count, _banner_auto_hide)`

Setups banner mediator. More info [here](#mediators).

**Parameters**

- order table _required_ Ad display order. This is an array that contains objects like `{id = network_id, count = 2}`.

- repeat_cut number _optional_ specified if after the first cycle in queue it is necessary to cut off a part of the order. Default: the total number of all networks.

- _banner_auto_hide boolean _optional_ The banner will be automatically hidden if `hide_banner` was called after `show_banner`, but the banner did not have time to load. Default: `false`

### `ads_wrapper.init(initilize_video, initilize_banner, callback)`

Initializes ads_wrapper. Callback consists `responses` field.

Queue: `check_connection->request_idfa->init`

**Parameters**

- initilize_video boolean _optional_  check if need to initialize video networks

- initilize_banner boolean _optional_ check if need to initialize banner networks

- callback function _optional_ callback with [response](#response).

### `ads_wrapper.init_video_networks(callback)`

Initialize video networks.

Queue: `check_connection->request_idfa->init`

**Parameters**

- callback function _optional_ callback with [response](#response)

### `ads_wrapper.init_banner_networks(callback)`

Initialize banner networks.

Queue: `check_connection->request_idfa->init`

**Parameters**

- callback function _optional_ callback with [response](#response)

### `ads_wrapper.load_rewarded(callback)`

Loads rewarded ads for next network.

Queue: `check_connection->request_idfa->init->load_rewarded`

**Parameters**

- callback function _optional_ callback with [response](#response)

**Return**

- id integer|nil id to cancel execution

### `ads_wrapper.show_rewarded(callback)`

Shows rewarded ads for next network. Callback contain a special `code` field with [events.C_SKIPPED](#response-codes) if the user skipped the ad.

Queue: `check_connection->request_idfa->init->load_rewarded->show_rewarded`

**Parameters**

- callback function _optional_ callback with [response](#response).

**Return**

- id integer|nil id to cancel execution

### `ads_wrapper.load_interstitial(callback)`

Loads interstitial ads for next network.

Queue: `check_connection->request_idfa->init->load_interstitial`

**Parameters**

- callback function _optional_ callback with [response](#response)

**Return**

- id integer|nil id to cancel execution

### `ads_wrapper.show_interstitial(callback)`

Shows interstitial ads for next network.

Queue: `check_connection->request_idfa->init->load_interstitial->show_interstitial`

**Parameters**

- callback function _optional_ callback with [response](#response)

**Return**

- id integer|nil id to cancel execution

### `ads_wrapper.load_banner(callback)`

Loads banner for for next network.

Queue: `check_connection->request_idfa->init->load_banner`

**Parameters**

- callback function _optional_ callback with [response](#response)

**Return**

- id integer|nil id to cancel execution

### `ads_wrapper.show_banner(callback)`

Shows setup banner for next network. Hides the previous banner if it was displayed.

Queue: `check_connection->request_idfa->init->load_banner->show_banner`

**Parameters**

- callback function _optional_ callback with [response](#response)

**Return**

- id integer|nil id to cancel execution

### `ads_wrapper.hide_banner(callback)`

Hides setup banner for current network.

**Parameters**

- callback function _optional_ callback with [response](#response)

### `ads_wrapper.unload_banner(callback)`

Unloads banner for current networks.

**Parameters**

- callback function _optional_ callback with [response](#response)

### `ads_wrapper.is_banner_setup()`

Check if the banner mediator is set up

**Return**

- value boolean

### `ads_wrapper.is_video_setup()`

Check if the interstitial and rewarded video mediator is set up

**Return**

- value boolean

### `ads_wrapper.is_initialized()`

Check if ads wrapper is initiailzed

**Return**

- value boolean

### `ads_wrapper.is_internet_connected()`

Checks for internet connection

**Return**

- value boolean

### `ads_wrapper.is_interstitial_loaded(check_current)`

Check if the interstitial video is loaded.

Default checks the `next` network in mediator.

**Parameters**

- check_current boolean _optional_ if need check current network. Default `false`

**Return**

- value boolean

### `ads_wrapper.is_rewarded_loaded(check_current)`

Check if the rewarded video is loaded.

Default checks the `next` network in mediator.

**Parameters**

- check_current boolean _optional_ if need check current network. Default `false`

**Return**

- value boolean

### `ads_wrapper.is_banner_loaded(check_current)`

Check if the banner is loaded.

Default checks the `next` network in mediator.

**Parameters**

- check_current boolean _optional_ if need check current network. Default `false`

**Return**

- value boolean

### `ads_wrapper.get_current_network(check_banner)`

Returns the current network pointed to by mediator

Default returns for the video mediator

**Parameters**

- check_banner boolean _optional_ if need to return mediator for banners. Default `false`

**Return**

- network table|nil

### `ads_wrapper.get_next_network(check_banner)`

Returns the next network pointed to by mediator

Default returns for the video mediator

**Parameters**

- check_banner boolean _optional_ if need to return mediator for banners. Default `false`

**Return**

- network table|nil

### `ads_wrapper.clear_networks()`

Remove all registered networks

### `ads_wrapper.cancel(id)`

Сancel execution of the next step in the queue.

For example, if you cancel **show_interstitial** while the ad is loading, then it will not be shown.

**Parameters**

- id number _required_ queue id received from the function

## Constants

Constants are used to set network parameters

* T_REWARDED hash("T_REWARDED")

* T_INTERSTITIAL hash("T_INTERSTITIAL")

* T_BANNER hash("T_BANNER")

## Platform

This module can be used in network settings.

```lua

local platform = require("ads_wrapper.platform")

```

Constants:

* PL_ANDROID hash("PL_ANDROID")

* PL_IOS hash("PL_IOS")

* PL_HTML5 hash("PL_HTML5")

* PL_OTHER hash("PL_OTHER")

### `platform.is_same(pl_value)`

**Parameters**

- pl_value hash _required_ One of the constants

Сheck if the platform is correct

**Return**

- value boolean

### `platform.get()`

Returns current hash platform

**Return**

- value hash

## Networks

You can use existing networks or create your own.

More information can be found at the links:

* [Test](docs/networks.md#test-networks)

* [Admob](docs/networks.md#admob)

* [Unity Ads](docs/networks.md#unity-ads)

* [Poki](docs/networks.md#poki)

* [Yandex](docs/networks.md#yandex)

* [Yandex Mobile Ads](docs/networks.md#yandex-mobile-ads)

* [Vk Bridge](docs/networks.md#vk-bridge)

* [Applovin Max](docs/networks.md#applovin-max)

* [Admob and Unity Ads](docs/networks.md#admob-and-unity-ads)

* [GameDistribution](docs/networks.md#gamedistribution)

* [IronSource](docs/networks.md#ironsource)

## Network Creation

You can create your own [network](docs/network-creation.md).

It is best to look at already made networks.

## Debug mode

You can include output to the console of all operations that are done when calling functions with the queue.

```lua

local events = require("ads_wrapper.events")

local queue = require("ads_wrapper.queue")

queue.set_verbose_mode(events.V_ALL)

```

Constants:

* events.V_NONE hash("V_NONE") Output nothing. Default value.

* events.V_ERROR hash("V_ERROR") Show all errors

* events.V_SUCCESS hash("V_SUCCESS") Show all success responses

* events.V_ALL hash("V_ALL") Show all messages

## Credits

Made by [PotatoJam](https://github.com/potatojam).

For example used:

[Dirty Larry](https://github.com/andsve/dirtylarry)

[Druid](https://github.com/Insality/druid)

### License

MIT license.