Додайте партнерську чи реферальну програму у свій застосунок на Capacitor або Ionic.

Чому застосунки на WebView можуть точніше зараховувати реферали

Нативний застосунок отримує точний збіг за введеним кодом, а перехід через магазин зіставляється згодом. Застосунок на WebView може отримати сам код, і то трьома способами:

• URL запуску. Укажіть Settings → General → Web app URL, і реферальні посилання вестимуть на нього відвідувачів із комп'ютера (а також із телефона, якщо для їхньої платформи немає сторінки в магазині), додаючи influto_code та influto_click. initialize читає обидва параметри й очищає адресний рядок.

• Глибокі посилання. listenForCapacitorLaunchUrls(InfluTo) передає в SDK URL холодного старту й кожну подію appUrlOpen. У Cordova викличте InfluTo.handleLaunchUrl(url).

• Play Install Referrer. Посилання на Google Play від InfluTo містять код і клік у параметрі referrer. Прочитайте його під час першого запуску плагіном Install Referrer і передайте в captureInstallReferrer.

Якщо коду немає, InfluTo зіставляє за кліком на посиланні протягом 72 годин. Характеристики пристроїв при цьому не порівнюються.

Крок 1: встановлення

Додайте пакет. На Capacitor три плагіни необов'язкові, але рекомендовані: @capacitor/device — для даних про пристрій, @capacitor/preferences — для сховища, яке переживає скидання WebView, і @capacitor/app — для глибоких посилань. Після їх додавання виконайте npx cap sync. Якщо плагінів немає, використовуються типові налаштування браузера.

Немає бандлера? Підключіть збірку для тега script з https://cdn.jsdelivr.net/npm/@influto/web@1/dist/index.global.js і користуйтеся window.InfluTo. Вона містить лише ядро SDK, а допоміжні підшляхи потребують бандлера.

npm install @influto/web
# Capacitor / Ionic apps (device info, storage, deep links):
npm install @capacitor/device @capacitor/preferences @capacitor/app

Крок 2: одна ініціалізація, у слушний момент

Викличте initialize один раз, у корені застосунку, і дочекайтеся результату. У разі збою вона кидає InfluToApiError (status, body): перехопіть його, запишіть у лог і працюйте далі. Наступного запуску спроба повториться. У таблиці нижче показано, коли викликати її в кожному середовищі.

API-ключ (it_…, у розділі Setup & SDK) діє і для розробки, і для продакшну. Тримайте його в .env.local, доданому в gitignore, і читайте через бандлер. Типовий старт Capacitor у застосунку з RevenueCat, по порядку:

import InfluTo from '@influto/web';
import { capacitorAdapters, listenForCapacitorLaunchUrls } from '@influto/web/capacitor';
import { revenueCatCapacitor } from '@influto/web/revenuecat';
import { Purchases } from '@revenuecat/purchases-capacitor';

export async function startInfluTo() {
  await Purchases.configure({ apiKey: 'appl_…' }); // RevenueCat apps: configure it first
  try {
    await InfluTo.initialize({
      apiKey: import.meta.env.VITE_INFLUTO_API_KEY,
      appVersion: '1.4.0',
      ...(await capacitorAdapters()),
      revenueCat: revenueCatCapacitor(Purchases),
    });
  } catch (error) {
    console.warn('InfluTo initialize failed', error); // retried on the next launch
    return;
  }
  await listenForCapacitorLaunchUrls(InfluTo); // deep links → referral claim
  const attribution = await InfluTo.checkAttribution();
  const { appUserID } = await Purchases.getAppUserID();
  await InfluTo.identifyUser(appUserID);
}

Крок 3: точне зарахування встановлень із Play Store

На Android прочитайте рядок referrer під час першого запуску через @capgo/capacitor-install-referrer або cordova-play-install-referrer і передайте його після initialize, перед checkAttribution. Код, отриманий пізніше, змінює раніше визначену відповідь «органічне». Встановлення з атрибуцією зберігає свого автора.

await InfluTo.captureInstallReferrer(referrer); // the raw referrer string from the plugin
const attribution = await InfluTo.checkAttribution();

Крок 4: дайте користувачам ввести код

applyCode(code) перевіряє код, який ввів користувач, і застосовує його, якщо він дійсний. Коди обрізаються від пробілів і переводяться у верхній регістр. Недійсний код повертає valid: false з error_code, наприклад CODE_NOT_FOUND або CODE_EXPIRED.

У React та Ionic React ReferralCodeInput з @influto/web/react — це проста форма без стилів: вона підставляє код, пов'язаний із посиланням, і застосовує його після надсилання. В Angular, Vue або без фреймворку зробіть поле на основі applyCode.

Крок 5: підключіть покупки

InfluTo виплачує комісію лише за покупки, перевірені магазином. Оберіть один шлях для кожної платформи:

• RevenueCat: передайте прив'язку як revenueCat: revenueCatCapacitor(Purchases) для @revenuecat/purchases-capacitor 7.5.10+, revenueCatCordova(window.Purchases) для cordova-plugin-purchases або revenueCatJs для purchases-js. Підключіть її перед checkAttribution, бо атрибут записується в момент, коли реферал знайдено. Невдалі записи повторюються до 3 разів.

• Store-direct: передайте purchaseSource (див. таблицю). Якщо в Settings → Validation для застосунку вибрано store-direct, initialize повідомляє про нові покупки й дозаповнює наявні, кожну один раз.

На iOS для store-direct потрібна підписана транзакція StoreKit 2: capgoNativePurchasesSource її передає, а з cordova-plugin-purchase переконайтеся, що ваше налаштування її надає. На Android ці джерела не передають ціни, тож разові товари повідомляйте самі, із price і currency, інакше їх буде записано як $0.

У TWA Digital Goods API не має події покупки, тому викликайте InfluTo.syncExistingPurchases() після кожної оплати. digitalGoodsSource сам дізнається ціну.

Підводні камені платформ

Більшість невдалих інтеграцій у WebView зводяться до одного з цих пунктів:

• Сховище Capacitor. Якщо встановлено @capacitor/preferences, SDK зберігає стан там. localStorage у WebView стирається, коли змінюється androidScheme або iosScheme.

• ionic serve. У вебзбірці для розробки плагін RevenueCat для Capacitor — лише заглушка, тому запис атрибутів там нічого не робить. Тестуйте на пристрої.

• Cordova за замовчуванням блокує API. У свіжому шаблоні потрібен запис access origin для https://influ.to у config.xml і connect-src https://influ.to у Content-Security-Policy. RevenueCat визнав застарілим свій плагін для Cordova; для нового застосунку краще обрати Capacitor.

• Браузери та PWA. У браузері чи PWA завжди передавайте platform (ios або android) у reportPurchase: SDK не вгадуватиме, коли виявляє веб. Веб-застосунки на головному екрані iOS не можуть продавати покупки в застосунку, але атрибуція все одно працює.

Крок 6: перевірте

Тестові покупки не рухають гроші й не змінюють вашу статистику:

1. 1

   Перевірте Setup & SDK. Після першого успішного initialize з’являється «SDK connected» із платформою, @influto/web і версією SDK; debug: true записує в лог кожен крок.

2. 2

   Симулюйте покупку. Кнопка Simulate a purchase у Setup & SDK надсилає тестову sandbox-покупку через справжній конвеєр InfluTo. Введіть один зі своїх кодів, щоб побачити, як він розпізнається.

3. 3

   Пройдіть шлях запрошеного користувача на пристрої. Відкрийте реферальне посилання автора на тестовому пристрої, встановіть застосунок, запустіть його й купіть через sandbox, TestFlight або license tester. Integration log у режимі Sandbox покаже покупку з атрибуцією.

clearAttribution() забуває збережену атрибуцію, код і код запуску, щоб можна було пройти все ще раз. Якщо кодувального агента підключено через MCP, він може виконати ці перевірки за вас.