links/mobile/SPOTLIGHT_SEARCH_README.md

iOS Spotlight Search Integration for Heygo

Overview

The Heygo iOS app now supports system-wide Spotlight search integration. Users can search for their links directly from the iOS search screen without opening the app.

How It Works

Searching for Links

1. Pull down from the home screen or swipe right to access iOS Spotlight search
2. Type "heygo" followed by a space and then the beginning of your link alias
   • Example: "heygo g" will show links that start with 'g' or contain 'g'
   • Example: "heygo github" will show links with "github" in the alias, description, or tags

Opening Links

When you tap on a search result:

• Regular Links: Opens the URL directly in your default browser
• Template Links:
  • If no parameters needed: Opens directly in browser
  • If parameters needed: Opens the app to input parameters
• Custom Links: Opens the app to display the custom content

Click Tracking

Every time you open a link through Spotlight search, the app automatically:

• Increments the click counter for that link
• Records a click log entry with timestamp
• Updates the link's ranking for future searches

Technical Implementation

Files Modified/Created

1. Utils/SpotlightSearchManager.swift - Core Spotlight integration logic
2. ViewModels/LinkViewModel.swift - Added automatic indexing when links are created/updated/deleted
3. HeygoApp.swift - Added user activity handling for Spotlight search results
4. ContentView.swift - Added notification handling for custom/template links

Key Features

• Automatic Indexing: Links are automatically indexed when created or updated
• Prefix Matching: Search supports partial matches (typing "g" finds "github", "google", etc.)
• Ranking: More frequently clicked links rank higher in search results
• Rich Metadata: Search results show link type icons and descriptions
• Clean Removal: Deleted links are automatically removed from search index

Search Optimization

The search implementation includes:

• App identifier keywords ("heygo", "link") for filtering
• Alias prefix matching for quick access
• Tag-based searching
• Link type classification
• Click-based ranking

Usage Examples

Quick Link Access

• Search: "heygo g" → Shows all links starting with 'g'
• Search: "heygo gmail" → Shows gmail-related links
• Search: "heygo" → Shows all your links

Tag-Based Search

• Search: "heygo work" → Shows links tagged with "work"
• Search: "heygo social" → Shows links tagged with "social"

Troubleshooting

Links Not Appearing in Search

1. Make sure the app has been opened recently (triggers indexing)
2. Try searching with "heygo" prefix
3. Check if Spotlight indexing is enabled in iOS Settings → Siri & Search → Heygo

Search Results Not Opening Correctly

1. Ensure the app is installed and not deleted
2. Check if the link still exists in your collection
3. For template links, make sure parameters are properly configured

Privacy Note

Link indexing happens locally on your device. Your links are not sent to Apple's servers beyond what's necessary for local Spotlight functionality.