Avada Components

A collection of React components built with Shopify Polaris for company-wide app usage.

Installation

# Using yarn
yarn add avada-components-seoon

# Using npm
npm install avada-components-seoon

Components

CrossAppBanner

A smart banner component that promotes other Avada apps to users. It automatically checks installation status and displays the highest priority non-installed app with a beautiful loading state.

Features

• ✨ Automatic installation status checking
• 🎯 Priority-based app display
• 💾 Remember dismissed banners per page
• 🔄 Loading skeleton during data fetching
• 📱 Responsive design with Shopify Polaris
• 🎨 Modern UI with smooth animations
• 🔧 Three configuration methods: Default, Legacy (with appIds), and Dynamic (with JSON config)

Configuration Methods

The component supports three different ways to configure which apps to display:

1. Default Method (Show all apps)

import { CrossAppBanner } from 'avada-components-seoon';

function App() {
  return <CrossAppBanner shopDomain="your-store.myshopify.com" />;
}

2. Legacy Method (Explicit appIds)

Specify exactly which apps to show in priority order:

import { CrossAppBanner } from 'avada-components-seoon';

function App() {
  return (
    <CrossAppBanner
      shopDomain="your-store.myshopify.com"
      appIds={['avada-seo-suite', 'ai-product-copy', 'seoon-blog']}
      clickInstallCallback={() => {
        console.log('User clicked install button');
      }}
    />
  );
}

3. Dynamic Method (JSON Configuration)

Recommended for multi-app environments: Configure apps dynamically from a JSON file without code changes:

import { CrossAppBanner } from 'avada-components-seoon';

function App() {
  return (
    <CrossAppBanner
      shopDomain="your-store.myshopify.com"
      appName="seoon"
      position="homePage"
      urlJson="https://cdn.example.com/bannerSeoApp.json"
      clickInstallCallback={() => {
        console.log('User clicked install button');
      }}
    />
  );
}

JSON Configuration Structure:

{
  "appSeoon": [
    {
      "title": "Avada SEO Suite",
      "description": "Boost your store's SEO",
      "image": "https://example.com/icon.png",
      "url": "https://apps.shopify.com/avada-seo-suite",
      "actionLabel": "Install Now",
      "key": "seo"
    }
  ],
  "appOutSide": [],
  "settingApp": {
    "seoon": {
      "homePage": ["avada-seo-suite", "seoon-blog"],
      "settingsPage": ["ai-product-copy"]
    }
  }
}

With this approach, you can manage banner configurations for different apps and pages from a single JSON file.

Key Mapping Reference:

The key field in JSON must match these values:

| App ID (appIds) | JSON Key (key) | | -------------------- | ------------------- | | avada-seo-suite | seo | | seoon-blog | blog | | ai-product-copy | aiCopy | | ap-speed-optimizer | plaza | | joy-loyalty | joy-loyalty | | chatty-ai | chatty-ai | | gem-pages-landing | gem-pages-landing |

Props

The component accepts different prop combinations depending on the configuration method:

Common Props (all methods):

| Prop | Type | Required | Default | Description | | ---------------------- | ------------ | -------- | ------- | ---------------------------------------------------------------- | | shopDomain | string | Yes | - | The Shopify domain of the store (e.g., 'my-store.myshopify.com') | | clickInstallCallback | () => void | No | - | Callback function triggered when user clicks the install button | | urlJson | string | No | - | URL to fetch banner data from |

Legacy Method Props:

| Prop | Type | Required | Description | | -------- | ------------- | -------- | --------------------------------------------- | | appIds | AppIdKeys[] | Yes | Array of app IDs to display in priority order |

Dynamic Method Props:

| Prop | Type | Required | Description | | ---------- | -------- | -------- | -------------------------------------------------------------------- | | appName | string | Yes | App name to lookup in JSON config (e.g., 'seoon', 'email-marketing') | | position | string | Yes | Page position identifier (e.g., 'homePage', 'settingsPage') |

Note: You can only use one configuration method at a time. TypeScript will prevent you from mixing methods.

Available App IDs

You can specify which apps to promote using the appIds prop (Legacy Method):

// SEOon Suite Apps
const SEOON_APPS = [
  'avada-seo-suite', // Avada SEO Suite
  'seoon-blog', // SEOon Blog
  'ai-product-copy', // AI Product Copy Writer
  'ap-speed-optimizer', // Speed Optimizer
];

// Other Avada Apps
const OTHER_APPS = [
  'joy-loyalty', // Joy Loyalty
  'chatty-ai', // Chatty AI
  'gem-pages-landing', // Gem Pages Landing
];

// Example: Only show SEO-related apps
<CrossAppBanner shopDomain="store.myshopify.com" appIds={['avada-seo-suite', 'ai-product-copy']} />;

Which Method Should You Use?

Use Default Method when:

• You want to show all available apps
• Simple implementation with no customization needed
• Quick integration for testing

Use Legacy Method when:

• You need app-specific customization in code
• Different apps need different configurations
• You prefer code-based configuration over JSON

Use Dynamic Method when: ⭐ Recommended

• Managing multiple apps from your organization
• Need to update configurations without redeploying code
• Different pages/sections need different app promotions
• Want centralized configuration management
• A/B testing different app combinations

How It Works

Default & Legacy Methods:

1. App Selection: Uses provided appIds or defaults to all available apps
2. Installation Check: Checks each app in priority order
3. Display Logic: Shows the first non-installed, non-dismissed app
4. Loading State: Displays a skeleton loader while fetching data
5. Dismissal: Users can dismiss the banner (saved in localStorage)

Dynamic Method:

1. Fetch Configuration: Loads JSON from urlJson
2. Lookup Config: Finds apps using settingApp[appName][position]
3. Get App List: Retrieves the configured app IDs for that location
4. Installation Check: Checks each app in the configured order
5. Display Logic: Shows the first non-installed, non-dismissed app
6. Flexibility: Change displayed apps by updating the JSON file (no code changes needed)

Styling

The component uses Shopify Polaris components and includes default styles. The banner automatically adapts to your Polaris theme.

If you need custom styling, you can override the CSS classes:

.AC-CrossAppBanner {
  /* Custom styles */
}

.AC-CrossAppBanner__Thumbnail {
  /* Customize thumbnail area */
}

.AC-CrossAppBanner__Content {
  /* Customize content area */
}

.AC-CrossAppBanner__Install {
  /* Customize install button area */
}

.AC-CrossAppBanner__Close {
  /* Customize close button */
}

SeoScore

A component for displaying SEO performance metrics and issues for a Shopify store.

import { SeoScore } from 'avada-components-seoon';

function App() {
  return (
    <SeoScore
      type="widget"
      shop={{
        shopifyDomain: 'my-store.myshopify.com',
      }}
    />
  );
}

Props

| Prop | Type | Required | Default | Description | | ------ | ---------------------- | -------- | ---------- | ------------------------------ | | type | 'widget' \| 'banner' | No | 'widget' | Display style of the SEO score | | shop | Shop | Yes | - | Shop information object |

TypeScript Support

This package is written in TypeScript and includes full type definitions with strict type safety:

import { CrossAppBanner, type CrossAppBannerProps, type AppIdKeys } from 'avada-components-seoon';

// Legacy method - type checked
const legacyProps: CrossAppBannerProps = {
  shopDomain: 'my-store.myshopify.com',
  appIds: ['avada-seo-suite', 'ai-product-copy'],
  clickInstallCallback: () => console.log('Clicked'),
};

// Dynamic method - type checked
const dynamicProps: CrossAppBannerProps = {
  shopDomain: 'my-store.myshopify.com',
  appName: 'seoon',
  position: 'homePage',
  urlJson: 'https://cdn.example.com/banner.json',
};

// TypeScript will prevent invalid combinations
const invalidProps: CrossAppBannerProps = {
  shopDomain: 'my-store.myshopify.com',
  appIds: ['avada-seo-suite'],
  appName: 'seoon', // ❌ Error: Cannot use both methods
  position: 'homePage',
};

// Use type helpers
const myApps: AppIdKeys[] = ['avada-seo-suite', 'seoon-blog'];

Examples

Example 1: Default Configuration

Show all available apps with default priority:

<CrossAppBanner shopDomain="store.myshopify.com" />

Example 2: Legacy Method - Specific Apps

Show only specific apps in a custom order:

<CrossAppBanner shopDomain="store.myshopify.com" appIds={['avada-seo-suite', 'ai-product-copy']} />

Example 3: Dynamic Method - Different Pages

Configure different banners for different pages using JSON:

// Home page
<CrossAppBanner
  shopDomain="store.myshopify.com"
  appName="seoon"
  position="homePage"
  urlJson="https://cdn.example.com/bannerSeoApp.json"
/>

// Settings page
<CrossAppBanner
  shopDomain="store.myshopify.com"
  appName="seoon"
  position="settingsPage"
  urlJson="https://cdn.example.com/bannerSeoApp.json"
/>

Example 4: With Analytics Tracking

Track user interactions:

<CrossAppBanner
  shopDomain="store.myshopify.com"
  appName="seoon"
  position="homePage"
  urlJson="https://cdn.example.com/bannerSeoApp.json"
  clickInstallCallback={() => {
    // Track to Google Analytics
    gtag('event', 'cross_app_banner_click', {
      app_name: 'seoon',
      position: 'homePage',
    });

    // Track to custom analytics
    analytics.track('Banner Install Clicked');
  }}
/>

Example 5: Multi-App Environment

Use dynamic configuration for multiple apps:

{
  "settingApp": {
    "seoon": {
      "homePage": ["avada-seo-suite", "seoon-blog"],
      "settingsPage": ["ai-product-copy"]
    },
    "email-marketing": {
      "homePage": ["joy-loyalty", "chatty-ai"],
      "campaignPage": ["gem-pages-landing"]
    }
  }
}

// In SEO app
<CrossAppBanner
  shopDomain="store.myshopify.com"
  appName="seoon"
  position="homePage"
  urlJson="https://cdn.example.com/bannerSeoApp.json"
/>

// In Email Marketing app
<CrossAppBanner
  shopDomain="store.myshopify.com"
  appName="email-marketing"
  position="homePage"
  urlJson="https://cdn.example.com/bannerSeoApp.json"
/>

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

ISC