Бібліотека AdManager, призначена для взаємодії з Google DFP.
AdManager - це бібліотека JavaScript для взаємодії з Google Publisher Tags (GPT) та Google DFP. Вона відповідає за завантаження бібліотеки GPT, а також за визначення та запит рекламного інвентарю. Нижче наведено документацію з конфігурації та використання.
AdManager може бути встановлено використовуючи yarn. Для цього ви можете скористатися CLI:
$ yarn add @broqit/AdManager --save
Або визначити його у файлі package.json:
"dependencies": {
"@broqit/AdManager": "latest"
}
Якщо ви не використовуєте менеджери пакетів, бібліотеку можна прямо завантажити з GitHub, використовуючи кнопку Download ZIP.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>AdManager Використання</title>
<script src="AdManager.min.js"></script>
</head>
<body>
<!--
This is the ad unit container. AdManager looks for all of the
[data-ad-unit] in the DOM and grabs the slot name to make a
request from DFP to fill those units.
-->
<div data-ad-unit="Unit_Name_in_DFP"></div>
<script>
( function () {
var config = {
account: 1234567,
inventory: [
{
slot: 'Unit_Name_in_DFP',
sizes: [
[ 728, 90 ],
[ 970, 250 ],
[ 1000, 220 ]
]
}
]
};
AdManager( config );
} () );
</script>
</body>
</html>
Для ініціалізації AdManager потрібен об'єкт конфігурації.
key | type |
---|---|
account |
Integer |
autoload |
Boolean |
clientType |
String |
inventory |
Array |
context |
String |
enabled |
Boolean |
targeting |
Array |
insertionEnabled |
Array |
insertion |
Object |
Приклад конфігурації:
{
account: 1234567,
clientType: 'desktop',
inventory: [
{
slot: 'Unit_Name_in_DFP',
sizes: [
[ 728, 90 ],
[ 970, 250 ],
[ 1000, 220 ]
]
}
]
}
Тип: Integer
За змовчуванням: null
, обов'язково вказується
Опис: Ваш мережевий код, знайдений у вкладці "Адміністратор" DFP
Тип: Boolean
За змовчуванням: true
Опис: Чи запускати процес ініціалізації банерів автоматично.
Тип: String
За змовчуванням: 'default'
, optional
Опис: Оголошується тип клієнта (наприклад, настільний комп'ютер, планшет або мобільний телефон). Значення може бути встановлене зовнішнім сценарієм виявлення клієнта і буде використовуватися для порівняння з кожною одиницею інвентаризації, щоб побачити, чи повинен товар відображатися для цього клієнта.
Наприклад, якщо виявлено десктопний пристрій, для цього значення слід встановити значення clientType: 'desktop'
та банери в масиві інвентарю, які збігаються (type: 'desktop'
) будуть відображені. Це дозволяє включати як десктопні, так і мобільні елементи інвентарю, але показувати лише відповідні відповідно до того, що clientType
встановлено значення під час завантаження.
Тип: Array
За змовчуванням: []
, обов'язково вказується
Опис: Масив з одного або кількох об'єктів, які визначають різні типи оголошень. Дивіться розділ «Інвентаризація» нижче. Більш детальну інформацію можна знайти в розділі inventory section below.
Приклад:
var config = {
// ...
inventory: [
{
slot: 'Unit_Name_1',
sizes: [
[ 728, 90 ],
[ 970, 250 ],
[ 1000, 220 ]
]
},
{
slot: 'Unit_Name_2',
sizes: [
[ 728, 90 ],
[ 970, 250 ],
[ 1000, 220 ]
]
},
// ...
]
};
Тип: String
За змовчуванням: 'body'
, необов'язково
Опис: Використовується як селектор JavaScript, який визначає контекст DOM, куди потрібно вставити рекламу. У стандартних випадках це буде статично, оскільки буде лише одна сторінка. У програмах нескінченної прокрутки може існувати кілька сторінок в одному вікні, і це дає можливість відрізнити одну сторінку від іншої.
Тип: Boolean
За змовчуванням: true
, необов'язково
Опис: Це дає можливість вимкнути AdManager.
Тип: Boolean
За змовчуванням: false
, необов'язково
Опис: Чи слід вмикати динамічне вставлення.
Тип: Object
Приклад Insertion:
{
pxBetweenUnits: 800,
adHeightLimit: 1000,
insertExclusion: [
'img',
'iframe',
'video',
'audio',
'.video',
'.audio',
'[data-ad-unit]'
]
}
Тип: Array
За змовчуванням:
[
'img',
'iframe',
'video',
'audio',
'.video',
'.audio',
'[data-ad-unit]'
]
Опис: При використанні функції динамічної вставки це дозволяє налаштувати, які елементи слід виключити під час пошуку дійсних точок вставки.
Тип: Integer
За змовчуванням: 800
, необов'язково
Опис: Мінімальна відстань між динамічно вставленими блоками.
Тип: Integer
За змовчуванням: 1000
, необов'язково
Опис: Максимальна висота для динамічно вставлених блоків.
Масив інвентарю – це сукупність об'єктів, які представляють різні позиції оголошень.
property name | тип | |
---|---|---|
slot |
String | |
sizes |
Array | |
type |
String | |
dynamic |
Boolean | |
localContext |
String | необов'язково (обов'язковий, якщо dynamic: true ) |
Приклад використання:
var config = {
// ...
inventory: [
{
slot: 'Article_Leaderboard',
sizes: [
[ 728, 90 ],
[ 970, 250 ],
[ 1000, 220 ]
],
type: 'desktop',
dynamic: false
},
{
slot: 'Article_Dynamic',
sizes: [
[ 300, 250 ],
[ 300, 600 ]
],
type: 'desktop',
dynamic: true,
localContext: '.entry-content'
}
// ...
]
};
Тип: String
Опис: Ім'я слота, визначене в DFP.
Тип: Array
Опис: Масив прийнятих розмірів для цього модуля. Має відповідати розмірам, визначеним у DFP.
Тип: String
Опис: Це можна використовувати для категоризації інвентарю. Наприклад, його можна використовувати для позначення того, чи призначений пристрій для настільних комп'ютерів або мобільних пристроїв. Це значення звіряється з clientType
.
Тип: Boolean
За змовчуванням: false
Опис: Це вмикає/вимикає динамічну вставку. Якщо значення задати false
, AdManager очікуватиме контейнер на сторінці з атрибутом data-ad-unit
та значення атрибута, що відповідає назві слота, визначеному в об'єкті Інвентаризація.
Тип: String
Опис: Це потрібно тільки для динамічної вставки. Рядок є селектором javaScript, який вказує точку вставки для нового оголошення.
Приклад:
var config = {
// ...
inventory: [
// ...
{
slot: 'Article_Dynamic',
sizes: [
[ 300, 250 ],
[ 300, 600 ]
],
type: 'desktop',
dynamic: true,
localContext: '.entry-content'
}
// ...
]
};
Користувацькі події javaScript з префіксом AdManager
.
event | джерело тригера |
---|---|
AdManager:libraryLoaded |
внутрішнє |
AdManager:adUnitRendered |
внутрішнє |
AdManager:slotsDefined |
внутрішнє |
AdManager:refresh |
зовнішнє |
AdManager:runSequence |
обидва варіанти |
AdManager:emptySlots |
зовнішнє |
AdManager:emptySlotsInContext |
зовнішнє |
AdManager:importConfig |
обидва варіанти |
Опис: Це спрацьовує один раз під час завантаження бібліотеки GPT.
Опис: Він спрацьовує щоразу, коли показується оголошення. Прив'яжіть до цієї події, щоб отримувати сповіщення про показ певного оголошення.
Parameter: unit
{Object}
name | type | description |
---|---|---|
name |
String | The slot name defined in DFP. |
id |
String | HTML id for the current ad wrapper. |
size |
Array | Indicates the pixel size of the rendered creative. |
isEmpty |
Boolean | true if no ad was returned for the slot, false otherwise. |
creativeId |
String | Creative ID of the rendered ad. |
lineItemId |
String | Line item ID of the rendered ad. |
serviceName |
String | Name of the service that rendered the slot. |
Опис: Це спрацьовує, коли слоти успішно визначені, але до показу оголошень.
Опис: Передайте масив назв слотів, які потрібно оновити. Слоти вже повинні бути в DOM.
Приклад використання:
document.dispatchEvent(new CustomEvent('AdManager:refresh', {
detail: ['Unit_Name_1', 'Unit_Name_2']
}));
Опис: Тригер для запуску повної кваліфікаційної послідовності: визначення позицій у DOM, визначення слотів DFP, таргетинг, запит на креатив та відображення.
Приклад використання:
document.dispatchEvent(new CustomEvent('AdManager:runSequence'));
Опис: Передайте масив назв слотів, які потрібно очистити.
Приклад використання:
$.event.trigger( 'AdManager:emptySlots', [ 'Unit_Name_1', 'Unit_Name_2' ] );
Опис: Передати масив назв слотів, які потрібно спорожнити у виділенні.
Приклад використання:
document.dispatchEvent(new CustomEvent('AdManager:emptySlotsInContext', {
detail: {
$context: document.querySelector('.entry-content'), // Defaults to the context set in the config.
removeContainer: true // Defaults to true
}
}));
Опис: Передайте об'єкт для імпорту нових значень конфігурації. Нова конфігурація перевизначить значення в поточній конфігурації.
Приклад використання:
document.dispatchEvent(new CustomEvent('AdManager:importConfig', {
detail: {
targeting: {
category: [
'athletics',
'technology',
'graphic design'
]
}
}
}));
Замітка: Ця функція не є обов'язковою.
Ця функція дозволяє AdManager динамічно вставляти змінну кількість нових позицій оголошень на льоту, без заздалегідь визначених рекламних контейнерів. Модуль Insertion.js містить логіку, яка аналізує DOM-вузли в заданій текстовій області, щоб визначити оптимальні місця, куди вставляти рекламу.
- Додавайте нові елементи інвентарю, які відображають максимально можливу кількість динамічно вставлених оголошень.
- Set the additional options
dynamic
andlocalContext
in the inventory config.
var config = {
// ...
inventory: [
// ...
{
slot: 'Dynamic_Unit_1',
sizes: [
[ 300, 250 ],
[ 300, 425 ],
[ 300, 600 ]
],
type: 'desktop',
dynamic: true,
localContext: '.entry-content'
},
{
slot: 'Dynamic_Unit_2',
sizes: [
[ 300, 250 ],
[ 300, 425 ],
[ 300, 600 ]
],
type: 'desktop',
dynamic: true,
localContext: '.entry-content'
},
{
slot: 'Dynamic_Unit_3',
sizes: [
[ 300, 250 ],
[ 300, 425 ],
[ 300, 600 ]
],
type: 'desktop',
dynamic: true,
localContext: '.entry-content'
}
]
};
AdManager( config );
- If a more specific outer/main context is needed (the default context is
body
), the propertycontext
can be added to the config. This is needed when keeping multiple contexts or articles separate, such as in infinite scroll applications. In the example below, it is.hentry
.
<body>
<div class="hentry">
<div class="entry-content">
<p>Paragraph 1</p>
<p>Paragraph 2</p>
<p>Paragraph 3</p>
</div>
</div>
<script type="text/javascript">
( function () {
var config = {
// ...
context: '.hentry',
inventory: [
{
// ...
dynamic: true,
localContext: '.entry-content'
}
]
}
};
AdManager( config );
} () );
</script>
</body>
Цей реліз включає в себе ряд основних оновлень та покращень у порівнянні з оригінальною версією https://github.com/athletics/AdManager.
Оновлено gulp до 4 версії
Використання jQuery
було видалено. Це було зроблено з метою забезпечення більшої гнучкості та незалежності від цієї бібліотеки.
Всі модулі були переписані використовуючи сучасний синтаксис ES6 класів. Це було зроблено з метою поліпшення структури коду та його читаємості.
Ми змінили GPT URL на новий, що надає офіційний сайт.
Ці зміни призначені для того, щоб поліпшити рівень ефективності та надійності нашої бібліотеки. Завдяки видаленню залежностей та використанню нових технологій, ми прагнемо зробити нашу бібліотеку ще кращою для вас!
Проєкт містить gulpfile.js для конкатенації та мініфікації.
To use first install gulp and the dependencies (yarn install
). The default gulp task (gulp
) will start the watch task.