@alexsab-ru/scripts 0.14.0 → 0.15.0

package/docs/campaign-guide.md

@@ -0,0 +1,234 @@
+# Persist Campaign Data
+
+Функционал для сохранения данных рекламных кампаний (UTM параметры, gclid и др.) в cookies браузера и отправки в dataLayer. Основан на популярном Google Tag Manager шаблоне.
+
+## Возможности
+
+- 🎯 Автоматическое сохранение UTM параметров и других данных кампании в cookies
+- 📊 Отправка данных в dataLayer для интеграции с аналитикой
+- 🔗 Сохранение referrer когда пользователь приходит с внешнего домена
+- ⚙️ Гибкая настройка параметров и поведения
+- 🚀 Простая интеграция с React, Vue, Next.js и другими фреймворками
+- 📱 Поддержка SPA (Single Page Applications)
+
+## Установка
+
+```bash
+npm install @alexsab-ru/scripts
+```
+
+## Быстрый старт
+
+```javascript
+import { initPersistCampaignData } from '@alexsab-ru/scripts';
+
+// Автоматическая инициализация при загрузке страницы
+initPersistCampaignData();
+```
+
+### Установка отдельных модулей
+
+```javascript
+// Всё сразу
+import { persistCampaignData } from '@alexsab-ru/scripts';
+
+// Только campaign модуль
+import { persistCampaignData } from '@alexsab-ru/scripts/campaign';
+
+// Конкретный файл
+import { persistCampaignData } from '@alexsab-ru/scripts/campaign/persist';
+```
+
+## API
+
+### `persistCampaignData(options)`
+
+Основная функция для сохранения данных кампании.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| `storeInCookie` | boolean | `true` | Сохранять ли данные в cookies |
+| `pushToDataLayer` | boolean | `true` | Отправлять ли данные в dataLayer |
+| `triggerParameters` | string[] | `['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'utm_id', 'gclid', 'yclid', 'ysclid']` | Параметры URL, которые триггерят сохранение |
+| `urlCookieName` | string | `'__gtm_campaign_url'` | Имя cookie для URL кампании |
+| `referrerCookieName` | string | `'__gtm_referrer'` | Имя cookie для referrer |
+| `dataLayerName` | string | `'dataLayer'` | Имя массива dataLayer |
+| `dataLayerKey` | string | `'originalLocation'` | Ключ в dataLayer для оригинального URL |
+| `cookieExpireDays` | number | `null` | Дни жизни cookie (null = session cookie) |
+
+**Возвращает:** `boolean` - успешность операции
+
+### `getCampaignData(options)`
+
+Получает сохраненные данные кампании из cookies.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| `urlCookieName` | string | `'__gtm_campaign_url'` | Имя cookie для URL кампании |
+| `referrerCookieName` | string | `'__gtm_referrer'` | Имя cookie для referrer |
+
+**Возвращает:** 
+```javascript
+{
+    campaignUrl: string | undefined,
+    referrer: string | undefined
+}
+```
+
+### `extractUtmParameters(url)`
+
+Извлекает UTM параметры из URL.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| `url` | string | `window.location.href` | URL для анализа |
+
+**Возвращает:**
+```javascript
+{
+    utm_source: string | null,
+    utm_medium: string | null,
+    utm_campaign: string | null,
+    utm_term: string | null,
+    utm_content: string | null,
+    utm_id: string | null,
+    gclid: string | null,
+    yclid: string | null,
+    ysclid: string | null
+}
+```
+
+### `initPersistCampaignData(options)`
+
+Автоматическая инициализация при загрузке страницы.
+
+**Параметры:** те же, что у `persistCampaignData`
+
+## Примеры использования
+
+### Базовое использование
+
+```javascript
+import { persistCampaignData } from '@alexsab-ru/scripts';
+
+// Запуск с настройками по умолчанию
+persistCampaignData();
+```
+
+### Кастомная настройка
+
+```javascript
+persistCampaignData({
+    storeInCookie: true,
+    pushToDataLayer: true,
+    triggerParameters: ['utm_source', 'utm_medium', 'fbclid', 'custom_param'],
+    cookieExpireDays: 30,
+    urlCookieName: 'my_campaign_url'
+});
+```
+
+### React приложение
+
+```javascript
+import React, { useEffect } from 'react';
+import { initPersistCampaignData } from '@alexsab-ru/scripts';
+
+function App() {
+    useEffect(() => {
+        initPersistCampaignData({
+            cookieExpireDays: 30
+        });
+    }, []);
+
+    return <div>Your App</div>;
+}
+```
+
+### Next.js
+
+```javascript
+// pages/_app.js
+import { useEffect } from 'react';
+import { initPersistCampaignData } from '@alexsab-ru/scripts';
+
+function MyApp({ Component, pageProps }) {
+    useEffect(() => {
+        initPersistCampaignData();
+    }, []);
+
+    return <Component {...pageProps} />;
+}
+
+export default MyApp;
+```
+
+### Vue.js
+
+```javascript
+// main.js или App.vue
+import { initPersistCampaignData } from '@alexsab-ru/scripts';
+
+export default {
+    mounted() {
+        initPersistCampaignData();
+    }
+};
+```
+
+### Получение сохраненных данных
+
+```javascript
+import { getCampaignData, extractUtmParameters } from '@alexsab-ru/scripts';
+
+// Получить данные из cookies
+const campaignData = getCampaignData();
+console.log('Campaign URL:', campaignData.campaignUrl);
+console.log('Referrer:', campaignData.referrer);
+
+// Извлечь UTM параметры
+const utmParams = extractUtmParameters();
+console.log('UTM Source:', utmParams.utm_source);
+```
+
+## Как это работает
+
+1. **Сохранение URL кампании**: Если в URL есть параметры из списка `triggerParameters`, полный URL сохраняется в cookie
+2. **Сохранение referrer**: Если пользователь пришел с внешнего домена, referrer сохраняется в отдельный cookie
+3. **DataLayer**: Текущий URL отправляется в dataLayer с событием `originalLocation`
+4. **Session cookies**: По умолчанию cookies создаются как session (удаляются при закрытии браузера)
+
+## Интеграция с аналитикой
+
+Данные из dataLayer можно использовать в Google Analytics, Adobe Analytics и других системах:
+
+```javascript
+// Google Analytics 4
+gtag('config', 'GA_MEASUREMENT_ID', {
+    page_title: 'Custom Page',
+    page_location: dataLayer.find(item => item.originalLocation)?.originalLocation
+});
+
+// Google Tag Manager
+// Используйте dataLayer переменные в тегах и триггерах
+```
+
+## Совместимость
+
+- ✅ Vanilla JavaScript
+- ✅ React
+- ✅ Vue.js
+- ✅ Next.js
+- ✅ Nuxt.js
+- ✅ Angular
+- ✅ SPA (Single Page Applications)
+- ✅ SSR (Server Side Rendering)
+
+## Лицензия
+
+MIT

package/examples/campaign-examples.js

@@ -0,0 +1,126 @@
+// Примеры использования Persist Campaign Data
+
+import { 
+    persistCampaignData, 
+    getCampaignData, 
+    extractUtmParameters, 
+    initPersistCampaignData 
+} from '@alexsab-ru/scripts';
+
+// 1. Простой запуск с настройками по умолчанию
+// Сохранит UTM параметры и gclid в cookies, отправит данные в dataLayer
+persistCampaignData();
+
+// 2. Автоматическая инициализация при загрузке страницы
+initPersistCampaignData();
+
+// 3. Настройка с кастомными параметрами
+persistCampaignData({
+    storeInCookie: true,
+    pushToDataLayer: true,
+    triggerParameters: ['utm_source', 'utm_medium', 'utm_campaign', 'fbclid', 'custom_param'],
+    urlCookieName: 'my_campaign_url',
+    referrerCookieName: 'my_referrer',
+    dataLayerName: 'customDataLayer',
+    dataLayerKey: 'originalPageUrl',
+    cookieExpireDays: 30 // cookie будет жить 30 дней
+});
+
+// 4. Только сохранение в cookies (без dataLayer)
+persistCampaignData({
+    storeInCookie: true,
+    pushToDataLayer: false,
+    cookieExpireDays: 90
+});
+
+// 5. Только отправка в dataLayer (без cookies)
+persistCampaignData({
+    storeInCookie: false,
+    pushToDataLayer: true,
+    dataLayerName: 'myDataLayer'
+});
+
+// 6. Получение сохраненных данных кампании
+const campaignData = getCampaignData();
+console.log('Campaign URL:', campaignData.campaignUrl);
+console.log('Referrer:', campaignData.referrer);
+
+// 7. Получение данных с кастомными именами cookies
+const customCampaignData = getCampaignData({
+    urlCookieName: 'my_campaign_url',
+    referrerCookieName: 'my_referrer'
+});
+
+// 8. Извлечение UTM параметров из текущего URL
+const utmParams = extractUtmParameters();
+console.log('UTM Source:', utmParams.utm_source);
+console.log('UTM Medium:', utmParams.utm_medium);
+console.log('UTM Campaign:', utmParams.utm_campaign);
+
+// 9. Извлечение UTM параметров из конкретного URL
+const specificUtmParams = extractUtmParameters('https://example.com/?utm_source=google&utm_medium=cpc');
+console.log('Specific UTM params:', specificUtmParams);
+
+// 10. Инициализация для SPA (Single Page Application)
+// Запускать только на первоначальной загрузке страницы
+if (!window.campaignDataPersisted) {
+    persistCampaignData();
+    window.campaignDataPersisted = true;
+}
+
+// 11. Интеграция с React
+import React, { useEffect } from 'react';
+
+function App() {
+    useEffect(() => {
+        // Запускаем только при первом рендере компонента
+        initPersistCampaignData({
+            cookieExpireDays: 30,
+            triggerParameters: ['utm_source', 'utm_medium', 'utm_campaign', 'gclid', 'fbclid']
+        });
+    }, []);
+
+    return <div>Your App</div>;
+}
+
+// 12. Интеграция с Vue.js
+// В main.js или App.vue
+import { initPersistCampaignData } from '@alexsab-ru/scripts';
+
+export default {
+    mounted() {
+        initPersistCampaignData();
+    }
+};
+
+// 13. Интеграция с Next.js
+// В _app.js
+import { useEffect } from 'react';
+import { initPersistCampaignData } from '@alexsab-ru/scripts';
+
+function MyApp({ Component, pageProps }) {
+    useEffect(() => {
+        initPersistCampaignData();
+    }, []);
+
+    return <Component {...pageProps} />;
+}
+
+// 14. Обработка ошибок
+const success = persistCampaignData({
+    storeInCookie: true,
+    pushToDataLayer: true
+});
+
+if (!success) {
+    console.error('Failed to persist campaign data');
+    // Можно отправить ошибку в систему мониторинга
+}
+
+// 15. Условное выполнение
+// Запускать только для определенных страниц
+if (window.location.pathname.includes('/landing/')) {
+    persistCampaignData({
+        cookieExpireDays: 7 // Короткий срок жизни для лендингов
+    });
+}

package/examples/nobounce-examples.js

@@ -0,0 +1,280 @@
+// Примеры использования NoBounce модуля
+
+import { 
+    initNoBounce, 
+    startNoBounce, 
+    getNoBounceStats,
+    stopNoBounce,
+    sendNoBounceNow
+} from '@alexsab-ru/scripts/nobounce';
+
+// ============================================
+// БАЗОВОЕ ИСПОЛЬЗОВАНИЕ
+// ============================================
+
+// 1. Простой запуск с настройками по умолчанию (15 секунд)
+startNoBounce();
+
+// 2. Запуск с кастомной задержкой
+startNoBounce(30); // 30 секунд
+
+// 3. Запуск с кастомным названием цели
+startNoBounce(20, 'EngagedUser');
+
+// ============================================
+// ПРОДВИНУТАЯ НАСТРОЙКА
+// ============================================
+
+// 4. Полная настройка
+initNoBounce({
+    delay: 25,                    // 25 секунд
+    goalName: 'QualityVisit',     // Кастомное название цели
+    goalParams: {                 // Дополнительные параметры
+        page_type: 'landing',
+        source: 'organic'
+    },
+    oncePerSession: true,         // Один раз за сессию
+    checkVisibility: true,        // Учитывать видимость страницы
+    debug: true                   // Включить отладку
+});
+
+// 5. Настройка для разных типов страниц
+const pageType = document.body.dataset.pageType;
+
+switch(pageType) {
+    case 'homepage':
+        initNoBounce({
+            delay: 10,
+            goalName: 'HomepageEngagement',
+            goalParams: { page_type: 'homepage' }
+        });
+        break;
+        
+    case 'product':
+        initNoBounce({
+            delay: 20,
+            goalName: 'ProductPageEngagement',
+            goalParams: { 
+                page_type: 'product',
+                product_id: document.body.dataset.productId 
+            }
+        });
+        break;
+        
+    case 'blog':
+        initNoBounce({
+            delay: 30,
+            goalName: 'BlogEngagement',
+            goalParams: { page_type: 'blog' }
+        });
+        break;
+        
+    default:
+        startNoBounce(15, 'DefaultEngagement');
+}
+
+// ============================================
+// УСЛОВНЫЙ ЗАПУСК
+// ============================================
+
+// 6. Запуск только для новых пользователей
+if (!localStorage.getItem('returning_user')) {
+    initNoBounce({
+        delay: 20,
+        goalName: 'NewUserEngagement',
+        goalParams: { user_type: 'new' }
+    });
+}
+
+// 7. Запуск только для трафика с рекламы
+const urlParams = new URLSearchParams(window.location.search);
+if (urlParams.get('utm_source') || urlParams.get('gclid')) {
+    initNoBounce({
+        delay: 15,
+        goalName: 'PaidTrafficEngagement',
+        goalParams: { 
+            traffic_type: 'paid',
+            utm_source: urlParams.get('utm_source') || 'unknown'
+        }
+    });
+}
+
+// 8. Разная задержка в зависимости от источника трафика
+const utmSource = urlParams.get('utm_source');
+let delay = 15; // по умолчанию
+
+if (utmSource === 'google') {
+    delay = 10; // быстрее для Google трафика
+} else if (utmSource === 'facebook') {
+    delay = 20; // медленнее для Facebook
+} else if (document.referrer.includes('organic')) {
+    delay = 25; // еще медленнее для органики
+}
+
+initNoBounce({
+    delay,
+    goalName: 'SourceBasedEngagement',
+    goalParams: { utm_source: utmSource || 'direct' }
+});
+
+// ============================================
+// КОНТРОЛЬ И МОНИТОРИНГ
+// ============================================
+
+// 9. Мониторинг статистики
+setInterval(() => {
+    const stats = getNoBounceStats();
+    if (stats) {
+        console.log('Время на странице:', stats);
+        
+        // Отправляем промежуточные цели
+        if (stats.visibleTime === 60 && !window.oneMinuteSent) {
+            reachGoal('OneMinuteOnPage', { visible_time: 60 });
+            window.oneMinuteSent = true;
+        }
+        
+        if (stats.visibleTime === 300 && !window.fiveMinutesSent) {
+            reachGoal('FiveMinutesOnPage', { visible_time: 300 });
+            window.fiveMinutesSent = true;
+        }
+    }
+}, 10000); // каждые 10 секунд
+
+// 10. Принудительная отправка при определенных действиях
+document.addEventListener('scroll', () => {
+    const scrollPercent = (window.scrollY / (document.body.scrollHeight - window.innerHeight)) * 100;
+    
+    if (scrollPercent > 75 && !window.deepScrollSent) {
+        sendNoBounceNow(); // Принудительно отправляем NoBounce
+        window.deepScrollSent = true;
+    }
+});
+
+// 11. Остановка таймера при определенных условиях
+window.addEventListener('beforeunload', () => {
+    const stats = getNoBounceStats();
+    
+    // Если пользователь быстро покидает страницу, не отправляем цель
+    if (stats && stats.visibleTime < 5) {
+        stopNoBounce();
+    }
+});
+
+// ============================================
+// ИНТЕГРАЦИЯ С ФРЕЙМВОРКАМИ
+// ============================================
+
+// 12. React Hook
+import { useEffect } from 'react';
+
+function useNoBounce(options = {}) {
+    useEffect(() => {
+        const manager = initNoBounce({
+            delay: 15,
+            ...options
+        });
+        
+        return () => {
+            if (manager) {
+                manager.stop();
+            }
+        };
+    }, []);
+}
+
+// В компоненте
+function MyComponent() {
+    useNoBounce({
+        goalName: 'ReactPageEngagement',
+        goalParams: { framework: 'react' }
+    });
+    
+    return <div>My Component</div>;
+}
+
+// 13. Vue.js Composable
+import { onMounted, onUnmounted } from 'vue';
+
+function useNoBounce(options = {}) {
+    let manager = null;
+    
+    onMounted(() => {
+        manager = initNoBounce({
+            delay: 15,
+            ...options
+        });
+    });
+    
+    onUnmounted(() => {
+        if (manager) {
+            manager.stop();
+        }
+    });
+    
+    return { manager };
+}
+
+// 14. Next.js App integration
+// В _app.js
+import { useRouter } from 'next/router';
+import { useEffect } from 'react';
+
+function MyApp({ Component, pageProps }) {
+    const router = useRouter();
+    
+    useEffect(() => {
+        const handleRouteChange = () => {
+            // Новая страница - инициализируем NoBounce
+            setTimeout(() => {
+                initNoBounce({
+                    goalName: 'NextJSPageEngagement',
+                    goalParams: { 
+                        route: router.pathname,
+                        framework: 'nextjs' 
+                    }
+                });
+            }, 100);
+        };
+        
+        handleRouteChange(); // Для первой загрузки
+        router.events.on('routeChangeComplete', handleRouteChange);
+        
+        return () => {
+            router.events.off('routeChangeComplete', handleRouteChange);
+        };
+    }, [router]);
+    
+    return <Component {...pageProps} />;
+}
+
+// ============================================
+// ТЕСТИРОВАНИЕ И ОТЛАДКА
+// ============================================
+
+// 15. Тестовый режим
+if (window.location.search.includes('nobounce_test=true')) {
+    initNoBounce({
+        delay: 3, // 3 секунды для тестирования
+        goalName: 'TestNoBounce',
+        debug: true,
+        oncePerSession: false // Позволяем многократную отправку
+    });
+}
+
+// 16. Отладочная информация
+window.debugNoBounce = () => {
+    const stats = getNoBounceStats();
+    console.table(stats);
+    
+    console.log('Manager:', getNoBounceManager());
+};
+
+// Добавляем в глобальный объект для отладки
+if (typeof window !== 'undefined') {
+    window.noBounceDebug = {
+        getStats: getNoBounceStats,
+        sendNow: sendNoBounceNow,
+        stop: stopNoBounce,
+        reset: resetNoBounce
+    };
+}

package/index.js

@@ -2,3 +2,5 @@ export * from './lib/analytics';
 export * from './lib/calltouch';
 export * from './lib/cookie';
 export * from './lib/form';
+export * from './lib/campaign';
+export * from './lib/nobounce';

package/lib/campaign/index.js

@@ -0,0 +1,5 @@
+// Campaign module exports
+export * from './persist-campaign-data';
+
+// Re-export default
+export { default } from './persist-campaign-data';