Документация Android / Capacitor

Android / Capacitor

Подключите JavaScript-игру, собранную через Capacitor: нативные push, игровые сообщения и опросы без Construct 3.

1. Android-проект и Firebase

Создайте ANDROID-проект в DK Push и получите Project ID и полный SDK / Client key с правами devices:write и events:write. Не добавляйте серверный ключ в игру. Нужен действующий доступ к DK Push.

Для push настройте FCM-провайдер в DK Push. Поместите google-services.json Android-приложения Firebase в android/app/google-services.json; package name должен совпадать с игрой. Серверный service-account JSON хранится в DK Push, а не в APK.

Сообщениям и опросам не нужны разрешение на уведомления или FCM-токен. Для этой интеграции не устанавливайте SDK сайта, Web Push service worker или Cordova-плагины из инструкции Construct.

2. Установите совместимые плагины Capacitor

Major-версии плагинов должны соответствовать существующему @capacitor/core. Для Capacitor 8 используйте команду ниже; для Capacitor 7 замените @8 на @7. Не обновляйте всю игру ради DK Push.

npm install @capacitor/push-notifications@8 @capacitor/app@8 @capacitor/browser@8
npx cap sync android

Добавьте белую иконку уведомлений с прозрачным фоном: android/app/src/main/res/drawable/notification_icon.png. DK Push использует имя ресурса notification_icon. Сохраните существующие Firebase, авторизацию, платежи и интеграции игры.

3. Добавьте SDK в игру

Скачайте модуль, сохраните как src/sdk/dk-capacitor.mjs и включите в сборку игры. Замените оба placeholder ниже реальными значениями. Создавайте один клиент на проект, а не на каждый кадр или уровень.

Скачать SDK для Capacitor
import { Capacitor, CapacitorHttp } from '@capacitor/core';
import { PushNotifications } from '@capacitor/push-notifications';
import { App } from '@capacitor/app';
import { Browser } from '@capacitor/browser';
import { createDKPush } from './sdk/dk-capacitor.mjs';

const dkPush = createDKPush({
  projectId: 'YOUR_PROJECT_ID',
  sdkKey: 'YOUR_FULL_SDK_CLIENT_KEY',
  plugins: { Capacitor, CapacitorHttp, PushNotifications, App, Browser },
});

dkPush.on('error', ({ code }) => console.warn('[DK Push]', code));
void dkPush.initialize().catch(() => {});

// Your Enable notifications button:
async function enableNotifications() {
  try { return await dkPush.requestNotificationPermission(); }
  catch { return false; }
}

Initialize регистрирует устройство без автоматического запроса разрешения. Вызовите requestNotificationPermission из своей кнопки. Результат true означает выдачу разрешения; синхронизацию токена подтверждает pushRegistered или getState().pushRegistered.

Игра должна оставаться доступной при недоступном API. SDK обращается через CapacitorHttp напрямую, без подмены глобального fetch и смены origin игры. Для нативного push нужен Android APK; браузерный предпросмотр не подтверждает его работу.

4. Покажите сообщения и обработайте действия

await dkPush.showMessage('level_complete', level, 500);

dkPush.on('messageAction', ({ action }) => {
  if (action === 'open_store') openYourShopScreen();
});
dkPush.on('ratingSubmitted', ({ rating }) => {
  // rating: 1–5
});

Используйте manual, session_start или level_complete. Level ID принимает число или строку, включая 0. Delay — миллисекунды: по умолчанию 500, максимум 10000. Announcement / Store Offer / Rating определяется кампанией DK Push.

Вызывайте после рекламы и переходов. SDK ждёт активное приложение и свободное окно до 30 секунд, но сам не распознаёт игровой процесс и рекламу. Обозначайте их через setGameBusy(true) и возвращайте false в finally. Таймерами, музыкой и управлением распоряжается игра.

dkPush.setGameBusy(true);
try { await showYourAdOrTransition(); }
finally { dkPush.setGameBusy(false); }

const state = dkPush.getState();
const dialogVisible = state.messageVisible || state.surveyVisible;

Методы показа возвращают true при показе и false, если подходящего контента нет или безопасный момент не наступил вовремя. Обрабатывайте отклонение Promise при ошибках инициализации или сети, чтобы игра продолжалась.

Игровые сообщения →

5. Вызывайте опросы отдельно

await dkPush.showSurvey('level_complete', level, 500);
dkPush.on('surveySubmitted', () => { /* Answer accepted. */ });

Создайте активный ANDROID-опрос с подходящим триггером и аудиторией. Сообщения и опросы используют Android-рендерер и общий замок окна. Выбирайте момент для обратной связи, не вызывайте оба метода после каждого уровня.

Опросы →

6. Проверьте APK на Android

Установите пересобранный APK на Android-устройство, разрешите уведомления и дождитесь pushRegistered. Проверьте устройство в DK Push, затем вручную отправьте Test Push. Проверьте фон, нажатие, холодный запуск, отказ в разрешении и возврат в приложение. Локальные тесты SDK не доказывают нативную доставку.

Нажатия на уведомления передают CLICKED только для этого проекта. Получение в foreground не считается открытием или кликом. OPEN_URL использует Capacitor Browser и только HTTP(S). Системный показ в foreground зависит от версии плагина и presentationOptions; принятие FCM не доказывает доставку.

HTTP 401: проверьте полный активный клиентский ключ. HTTP 402: продлите доступ к DK Push. HTTP 403: проверьте права ключа и проект. Ошибка нативной регистрации: проверьте версии плагинов, package name Firebase и google-services.json. Не выводите SDK-ключи и FCM-токены.

Официальная документация Capacitor Push →