luckiest-co 1.0.0 → 1.0.3

package/skills/luckiest-analytics/references/gtm-implementation.md

@@ -0,0 +1,390 @@
+# Google Tag Manager Implementation Reference
+
+Detailed guide for implementing tracking via Google Tag Manager.
+
+## Contents
+- Container Structure (tags, triggers, variables)
+- Naming Conventions
+- Data Layer Patterns
+- Common Tag Configurations (GA4 configuration tag, GA4 event tag, Facebook pixel)
+- Preview and Debug
+- Workspaces and Versioning
+- Consent Management
+- Advanced Patterns (tag sequencing, exception handling, custom JavaScript variables)
+
+## Container Structure
+
+### Tags
+
+Tags are code snippets that execute when triggered.
+
+**Common tag types:**
+- GA4 Configuration (base setup)
+- GA4 Event (custom events)
+- Google Ads Conversion
+- Facebook Pixel
+- LinkedIn Insight Tag
+- Custom HTML (for other pixels)
+
+### Triggers
+
+Triggers define when tags fire.
+
+**Built-in triggers:**
+- Page View: All Pages, DOM Ready, Window Loaded
+- Click: All Elements, Just Links
+- Form Submission
+- Scroll Depth
+- Timer
+- Element Visibility
+
+**Custom triggers:**
+- Custom Event (from dataLayer)
+- Trigger Groups (multiple conditions)
+
+### Variables
+
+Variables capture dynamic values.
+
+**Built-in (enable as needed):**
+- Click Text, Click URL, Click ID, Click Classes
+- Page Path, Page URL, Page Hostname
+- Referrer
+- Form Element, Form ID
+
+**User-defined:**
+- Data Layer variables
+- JavaScript variables
+- Lookup tables
+- RegEx tables
+- Constants
+
+---
+
+## Naming Conventions
+
+### Recommended Format
+
+```
+[Type] - [Description] - [Detail]
+
+Tags:
+GA4 - Event - Signup Completed
+GA4 - Config - Base Configuration
+FB - Pixel - Page View
+HTML - LiveChat Widget
+
+Triggers:
+Click - CTA Button
+Submit - Contact Form
+View - Pricing Page
+Custom - signup_completed
+
+Variables:
+DL - user_id
+JS - Current Timestamp
+LT - Campaign Source Map
+```
+
+---
+
+## Data Layer Patterns
+
+### Basic Structure
+
+```javascript
+// Initialize (in <head> before GTM)
+window.dataLayer = window.dataLayer || [];
+
+// Push event
+dataLayer.push({
+  'event': 'event_name',
+  'property1': 'value1',
+  'property2': 'value2'
+});
+```
+
+### Page Load Data
+
+```javascript
+// Set on page load (before GTM container)
+window.dataLayer = window.dataLayer || [];
+dataLayer.push({
+  'pageType': 'product',
+  'contentGroup': 'products',
+  'user': {
+    'loggedIn': true,
+    'userId': '12345',
+    'userType': 'premium'
+  }
+});
+```
+
+### Form Submission
+
+```javascript
+document.querySelector('#contact-form').addEventListener('submit', function() {
+  dataLayer.push({
+    'event': 'form_submitted',
+    'formName': 'contact',
+    'formLocation': 'footer'
+  });
+});
+```
+
+### Button Click
+
+```javascript
+document.querySelector('.cta-button').addEventListener('click', function() {
+  dataLayer.push({
+    'event': 'cta_clicked',
+    'ctaText': this.innerText,
+    'ctaLocation': 'hero'
+  });
+});
+```
+
+### E-commerce Events
+
+```javascript
+// Product view
+dataLayer.push({ ecommerce: null }); // Clear previous
+dataLayer.push({
+  'event': 'view_item',
+  'ecommerce': {
+    'items': [{
+      'item_id': 'SKU123',
+      'item_name': 'Product Name',
+      'price': 99.99,
+      'item_category': 'Category',
+      'quantity': 1
+    }]
+  }
+});
+
+// Add to cart
+dataLayer.push({ ecommerce: null });
+dataLayer.push({
+  'event': 'add_to_cart',
+  'ecommerce': {
+    'items': [{
+      'item_id': 'SKU123',
+      'item_name': 'Product Name',
+      'price': 99.99,
+      'quantity': 1
+    }]
+  }
+});
+
+// Purchase
+dataLayer.push({ ecommerce: null });
+dataLayer.push({
+  'event': 'purchase',
+  'ecommerce': {
+    'transaction_id': 'T12345',
+    'value': 99.99,
+    'currency': 'USD',
+    'tax': 5.00,
+    'shipping': 10.00,
+    'items': [{
+      'item_id': 'SKU123',
+      'item_name': 'Product Name',
+      'price': 99.99,
+      'quantity': 1
+    }]
+  }
+});
+```
+
+---
+
+## Common Tag Configurations
+
+### GA4 Configuration Tag
+
+**Tag Type:** Google Analytics: GA4 Configuration
+
+**Settings:**
+- Measurement ID: G-XXXXXXXX
+- Send page view: Checked (for pageviews)
+- User Properties: Add any user-level dimensions
+
+**Trigger:** All Pages
+
+### GA4 Event Tag
+
+**Tag Type:** Google Analytics: GA4 Event
+
+**Settings:**
+- Configuration Tag: Select your config tag
+- Event Name: {{DL - event_name}} or hardcode
+- Event Parameters: Add parameters from dataLayer
+
+**Trigger:** Custom Event with event name match
+
+### Facebook Pixel - Base
+
+**Tag Type:** Custom HTML
+
+```html
+<script>
+  !function(f,b,e,v,n,t,s)
+  {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
+  n.callMethod.apply(n,arguments):n.queue.push(arguments)};
+  if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
+  n.queue=[];t=b.createElement(e);t.async=!0;
+  t.src=v;s=b.getElementsByTagName(e)[0];
+  s.parentNode.insertBefore(t,s)}(window, document,'script',
+  'https://connect.facebook.net/en_US/fbevents.js');
+  fbq('init', 'YOUR_PIXEL_ID');
+  fbq('track', 'PageView');
+</script>
+```
+
+**Trigger:** All Pages
+
+### Facebook Pixel - Event
+
+**Tag Type:** Custom HTML
+
+```html
+<script>
+  fbq('track', 'Lead', {
+    content_name: '{{DL - form_name}}'
+  });
+</script>
+```
+
+**Trigger:** Custom Event - form_submitted
+
+---
+
+## Preview and Debug
+
+### Preview Mode
+
+1. Click "Preview" in GTM
+2. Enter site URL
+3. GTM debug panel opens at bottom
+
+**What to check:**
+- Tags fired on this event
+- Tags not fired (and why)
+- Variables and their values
+- Data layer contents
+
+### Debug Tips
+
+**Tag not firing:**
+- Check trigger conditions
+- Verify data layer push
+- Check tag sequencing
+
+**Wrong variable value:**
+- Check data layer structure
+- Verify variable path (nested objects)
+- Check timing (data may not exist yet)
+
+**Multiple firings:**
+- Check trigger uniqueness
+- Look for duplicate tags
+- Check tag firing options
+
+---
+
+## Workspaces and Versioning
+
+### Workspaces
+
+Use workspaces for team collaboration:
+- Default workspace for production
+- Separate workspaces for large changes
+- Merge when ready
+
+### Version Management
+
+**Best practices:**
+- Name every version descriptively
+- Add notes explaining changes
+- Review changes before publish
+- Keep production version noted
+
+**Version notes example:**
+```
+v15: Added purchase conversion tracking
+- New tag: GA4 - Event - Purchase
+- New trigger: Custom Event - purchase
+- New variables: DL - transaction_id, DL - value
+- Tested: Chrome, Safari, Mobile
+```
+
+---
+
+## Consent Management
+
+### Consent Mode Integration
+
+```javascript
+// Default state (before consent)
+gtag('consent', 'default', {
+  'analytics_storage': 'denied',
+  'ad_storage': 'denied'
+});
+
+// Update on consent
+function grantConsent() {
+  gtag('consent', 'update', {
+    'analytics_storage': 'granted',
+    'ad_storage': 'granted'
+  });
+}
+```
+
+### GTM Consent Overview
+
+1. Enable Consent Overview in Admin
+2. Configure consent for each tag
+3. Tags respect consent state automatically
+
+---
+
+## Advanced Patterns
+
+### Tag Sequencing
+
+**Setup tags to fire in order:**
+Tag Configuration > Advanced Settings > Tag Sequencing
+
+**Use cases:**
+- Config tag before event tags
+- Pixel initialization before tracking
+- Cleanup after conversion
+
+### Exception Handling
+
+**Trigger exceptions** - Prevent tag from firing:
+- Exclude certain pages
+- Exclude internal traffic
+- Exclude during testing
+
+### Custom JavaScript Variables
+
+```javascript
+// Get URL parameter
+function() {
+  var params = new URLSearchParams(window.location.search);
+  return params.get('campaign') || '(not set)';
+}
+
+// Get cookie value
+function() {
+  var match = document.cookie.match('(^|;) ?user_id=([^;]*)(;|$)');
+  return match ? match[2] : null;
+}
+
+// Get data from page
+function() {
+  var el = document.querySelector('.product-price');
+  return el ? parseFloat(el.textContent.replace('$', '')) : 0;
+}
+```

package/skills/luckiest-aso/ATTRIBUTION.md

@@ -0,0 +1,40 @@
+# Attribution
+
+This skill, **luckiest-aso**, is a rebranded and hardened "Luckiest edition" derived from the
+original skill **aso** from the marketingskills project.
+
+- Original skill: `aso`
+- Project: marketingskills (https://github.com/coreyhaines31/marketingskills)
+- Author: Corey Haines (https://corey.co)
+- License: MIT
+
+The original copyright and license are preserved verbatim below. Modifications for the
+Luckiest edition (security review, best-practices restructuring, a cold-start scoring
+exception, added trigger phrases, a Luckiest-network share hook, rebranding, and versioning)
+are documented in CHANGELOG.md.
+
+---
+
+## Original LICENSE (MIT)
+
+MIT License
+
+Copyright (c) 2025 Corey Haines
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/luckiest-aso/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog — luckiest-aso
+
+## 1.1.0 — 2026-07-06
+Skill updater pass: analytics integration.
+
+### Analytics (report_usage)
+- Updated `report_usage` call to `skill_version: "1.1.0"` and `check_updates`
+  `installedSemver: "1.1.0"`. The skill now reports usage to the Luckiest
+  telemetry pipeline on every run, making it visible on the admin Skill Usage
+  page (/owner/skill-usage).
+
+## 1.0.0 — 2026-07-01
+Rebranded from aso (marketingskills, MIT).
+
+### Improve pass (/refract)
+- Added a cold-start exception to Phase 1.5: brand-new apps (roughly <50 ratings or a
+  bottom download range) are not docked on Ratings & Reviews for low volume; that
+  dimension is scored on rating quality and recency relative to app age instead.
+- Added missing natural trigger phrases to the description: "app store audit,"
+  "Play Store listing," and "grade my app listing."
+
+### Network hook
+- Added a "Share with your tribe" section: after an audit, the skill OFFERS (never
+  auto-posts) to surface the audit to the user's Luckiest tribe working on same-category
+  apps. Guards against sharing App Store Connect / Play Console data or a competitor's
+  private analysis without an explicit ask.
+
+### Trend pass (/newsjack + /luckiest-trends)
+- No actionable signal. The trends engine requires Python 3.12+ and an interactive
+  first-run scrape that is unavailable in this non-interactive session; fabricating
+  signal is prohibited. The two dated ASO facts the source already cites (screenshot
+  captions indexed June 2025; Custom Product Pages in organic search July 2025) remain
+  accurate and unchanged.