Installation Guide

Get started with Scriptable iOS Widgets in just a few simple steps!

Installation Preview

📱 Prerequisites

Before you begin, make sure you have:

• iOS 14 or later (required for widgets)

• Scriptable app (free from App Store)

• Internet connection (for API-based widgets)

🚀 Step-by-Step Installation

1. Install Scriptable App

1. Open the App Store on your iOS device

2. Search for "Scriptable"

3. Download and install the app (it's free!)

4. Open Scriptable to complete setup

2. Choose Your Widget

Browse our widget collection and pick the one you want to install. Each widget has:

• Detailed documentation with setup instructions

• Configuration options for customization

• Source code ready to copy and paste

3. Copy Widget Code

1. Visit the widget's documentation page

2. Click the "View Source Code" link

3. Copy the entire JavaScript code

4. Keep it in your clipboard

4. Create Script in Scriptable

1. Open the Scriptable app

2. Tap the "+" button to create a new script

3. Paste the copied code

4. Rename the script (e.g., "Weather Widget")

5. Tap "Done" to save

5. Configure Widget Settings

Most widgets require some configuration:

• API keys (for weather, GitHub stats, etc.)

• Personal information (birth dates, usernames, etc.)

• Preferences (colors, display options, etc.)

Follow the specific instructions in each widget's documentation.

6. Test the Widget

1. Tap the play button in Scriptable

2. Verify the widget displays correctly

3. Check for any error messages

4. Make adjustments if needed

7. Add to Home Screen

1. Long press on your home screen

2. Tap the "+" in the top-left corner

3. Search for "Scriptable"

4. Choose your preferred widget size

5. Tap "Add Widget"

6. Tap the widget to configure it

7. Select your script and adjust settings

8. Tap outside to finish

⚙️ Widget Configuration

Accessing Widget Settings

After adding a widget to your home screen:

1. Long press the widget

2. Select "Edit Widget"

3. Choose your script

4. Set parameters if needed

5. Tap "Done"

Common Settings

Most widgets support these parameters:

• Script: Choose which Scriptable script to run

• When Interacting: Choose "Run Script" or "Open App"

• Parameter: Optional text for widget customization

🔧 Troubleshooting

Widget Not Loading

Check these common issues:

• ✅ Script is saved in Scriptable

• ✅ Required API keys are configured

• ✅ Internet connection is available

• ✅ Location permissions granted (if needed)

• ✅ Widget size matches script requirements

Error Messages

"Script not found":

• Ensure script name matches exactly

• Check for typos in script selection

"API Error" or "Network Error":

• Verify API keys are correct and active

• Check internet connection

• Try running script manually in Scriptable

"Permission Denied":

• Enable location services for Scriptable

• Grant necessary permissions in iOS Settings

Performance Issues

Widget loading slowly:

• Check internet connection speed

• Reduce refresh frequency if configurable

• Clear Scriptable app cache

Battery drain:

• Widgets update automatically on schedule

• Most widgets are optimized for efficiency

• Consider reducing update frequency for complex widgets

📚 Advanced Tips

Multiple Widget Instances

You can have multiple instances of the same widget:

1. Duplicate the script in Scriptable

2. Configure each differently (different locations, users, etc.)

3. Name them uniquely (e.g., "Weather Home", "Weather Work")

4. Add separate widgets to home screen

Widget Sizes Guide

Size	Dimensions	Best For	Typical Content
Small	2x2	Quick info	Temperature, single stat
Medium	4x2	Balanced view	Weather + forecast
Large	4x4	Detailed info	Full dashboard

Customization Tips

• Read the documentation for each widget thoroughly

• Test configurations in Scriptable before adding to home screen

• Start with defaults and customize gradually

• Join the community for tips and custom configurations

🔄 Updating Widgets

Manual Updates

1. Copy new code from the repository

2. Open existing script in Scriptable

3. Replace old code with new version

4. Update configuration if needed

5. Test before using

Automatic Updates

Currently, widgets don't auto-update. We recommend:

• Star the repository to get notified of updates

• Check back periodically for new features

• Follow release notes for breaking changes

🆘 Getting Help

Documentation

• Widget-specific docs: Each widget has detailed setup instructions

• Troubleshooting guides: Common issues and solutions

• Configuration examples: Sample setups and customizations

Community Support

• GitHub Issues: Report bugs and ask questions

• Discussions: Share tips and get help

• Examples: Check existing issues for similar problems

Before Asking for Help

Please include:

• Widget name and version

• iOS version and device model

• Error messages (screenshots help!)

• Configuration details (remove sensitive info like API keys)

• Steps to reproduce the issue

---

🎉 You're All Set!

Congratulations! You should now have beautiful, functional widgets on your iOS home screen.

What's next?

• Explore more widgets from our collection

• Customize colors and settings to match your style

• Share your setups with the community

• Consider contributing improvements or new widgets

Enjoy your enhanced iOS experience! 📱✨