Added onboarding progress tracking & landing page
This commit is contained in:
ajaysi
300
docs/WIX_INTEGRATION_README.md
Normal file
300
docs/WIX_INTEGRATION_README.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# Wix Integration for ALwrity
|
||||
|
||||
This document describes the Wix integration feature that allows ALwrity users to publish their generated blogs directly to their Wix websites.
|
||||
|
||||
## Overview
|
||||
|
||||
The Wix integration provides a seamless way for ALwrity users to:
|
||||
- Connect their Wix account to ALwrity
|
||||
- Publish blog posts directly from ALwrity to their Wix website
|
||||
- Manage blog categories and tags
|
||||
- Import images to Wix Media Manager
|
||||
|
||||
## Architecture
|
||||
|
||||
### Backend Components
|
||||
|
||||
1. **WixService** (`services/wix_service.py`)
|
||||
- Handles OAuth 2.0 authentication with Wix
|
||||
- Manages token refresh and validation
|
||||
- Converts content to Wix Ricos JSON format
|
||||
- Imports images to Wix Media Manager
|
||||
- Creates and publishes blog posts
|
||||
|
||||
2. **Wix Routes** (`api/wix_routes.py`)
|
||||
- `/api/wix/auth/url` - Get OAuth authorization URL
|
||||
- `/api/wix/auth/callback` - Handle OAuth callback
|
||||
- `/api/wix/connection/status` - Check connection status
|
||||
- `/api/wix/publish` - Publish blog post to Wix
|
||||
- `/api/wix/categories` - Get blog categories
|
||||
- `/api/wix/tags` - Get blog tags
|
||||
- `/api/wix/disconnect` - Disconnect Wix account
|
||||
|
||||
### Frontend Components
|
||||
|
||||
1. **WixTestPage** (`frontend/src/components/WixTestPage/WixTestPage.tsx`)
|
||||
- Test page for Wix integration functionality
|
||||
- Connection status display
|
||||
- Blog post creation and publishing form
|
||||
- Category and tag management
|
||||
|
||||
2. **Enhanced Publisher** (`frontend/src/components/BlogWriter/Publisher.tsx`)
|
||||
- Integrated Wix publishing into existing blog writer
|
||||
- Connection status checking
|
||||
- Enhanced error handling and user feedback
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
### 1. Wix App Configuration
|
||||
|
||||
1. Go to [Wix Developers](https://dev.wix.com/)
|
||||
2. Create a new app or use an existing one
|
||||
3. Configure OAuth settings:
|
||||
- Redirect URI: `http://localhost:3000/wix/callback` (for development)
|
||||
- Scopes: `BLOG.CREATE-DRAFT`, `BLOG.PUBLISH`, `MEDIA.MANAGE`
|
||||
4. Note down your Client ID (no Client Secret required for Wix Headless OAuth)
|
||||
|
||||
### 2. Environment Configuration
|
||||
|
||||
Add the following environment variables to your `.env` file:
|
||||
|
||||
```bash
|
||||
# Wix Integration (Headless OAuth - Client ID only, no Client Secret required)
|
||||
WIX_CLIENT_ID=your_wix_client_id_here
|
||||
WIX_REDIRECT_URI=http://localhost:3000/wix/callback
|
||||
```
|
||||
|
||||
**Important Note**: Wix Headless OAuth only requires a Client ID and does NOT use a Client Secret. This is different from traditional OAuth implementations and is designed for public clients like single-page applications.
|
||||
|
||||
### 3. Database Setup
|
||||
|
||||
The integration requires storing user tokens securely. You'll need to:
|
||||
|
||||
1. Create a table to store Wix tokens:
|
||||
```sql
|
||||
CREATE TABLE wix_tokens (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
user_id TEXT NOT NULL,
|
||||
access_token TEXT NOT NULL,
|
||||
refresh_token TEXT,
|
||||
expires_at TIMESTAMP,
|
||||
member_id TEXT, -- Store member ID for third-party app requirements
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
2. Implement token storage and retrieval functions in the WixService
|
||||
|
||||
### 4. Important: Third-Party App Requirements
|
||||
|
||||
**CRITICAL**: When creating blog posts as a third-party app, Wix requires a `memberId` field. This is mandatory and cannot be omitted. The integration will:
|
||||
|
||||
1. Automatically retrieve the current member ID during the OAuth flow
|
||||
2. Store the member ID with the user's tokens
|
||||
3. Use the member ID when creating blog posts
|
||||
|
||||
This requirement is enforced by Wix's API and cannot be bypassed.
|
||||
|
||||
## Usage
|
||||
|
||||
### 1. Testing the Integration
|
||||
|
||||
1. Navigate to `/wix-test` in your ALwrity application
|
||||
2. Click "Connect to Wix" to authorize the integration
|
||||
3. Complete the OAuth flow in the popup window
|
||||
4. Once connected, you can:
|
||||
- Load categories and tags from your Wix blog
|
||||
- Create and publish test blog posts
|
||||
- Check connection status
|
||||
|
||||
### 2. Publishing from Blog Writer
|
||||
|
||||
1. Generate your blog content using ALwrity's AI tools
|
||||
2. Use the CopilotKit action: "Publish to Wix"
|
||||
3. The system will:
|
||||
- Check your Wix connection status
|
||||
- Convert your content to Wix format
|
||||
- Import any images to Wix Media Manager
|
||||
- Create and publish the blog post
|
||||
- Return the published post URL
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Authentication
|
||||
|
||||
#### Get Authorization URL
|
||||
```http
|
||||
GET /api/wix/auth/url?state=optional_state
|
||||
```
|
||||
|
||||
#### Handle OAuth Callback
|
||||
```http
|
||||
POST /api/wix/auth/callback
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"code": "authorization_code",
|
||||
"state": "optional_state"
|
||||
}
|
||||
```
|
||||
|
||||
### Connection Management
|
||||
|
||||
#### Check Connection Status
|
||||
```http
|
||||
GET /api/wix/connection/status
|
||||
```
|
||||
|
||||
#### Disconnect Account
|
||||
```http
|
||||
POST /api/wix/disconnect
|
||||
```
|
||||
|
||||
### Publishing
|
||||
|
||||
#### Publish Blog Post
|
||||
```http
|
||||
POST /api/wix/publish
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"title": "Blog Post Title",
|
||||
"content": "Blog content in markdown",
|
||||
"cover_image_url": "https://example.com/image.jpg",
|
||||
"category_ids": ["category_id_1"],
|
||||
"tag_ids": ["tag_id_1", "tag_id_2"],
|
||||
"publish": true
|
||||
}
|
||||
```
|
||||
|
||||
### Content Management
|
||||
|
||||
#### Get Blog Categories
|
||||
```http
|
||||
GET /api/wix/categories
|
||||
```
|
||||
|
||||
#### Get Blog Tags
|
||||
```http
|
||||
GET /api/wix/tags
|
||||
```
|
||||
|
||||
## Content Format Conversion
|
||||
|
||||
The integration automatically converts ALwrity's markdown content to Wix's Ricos JSON format:
|
||||
|
||||
### Supported Elements
|
||||
|
||||
- **Headings**: `# Heading` → `HEADING` node
|
||||
- **Paragraphs**: Regular text → `PARAGRAPH` node
|
||||
- **Images**: External URLs → Imported to Wix Media Manager
|
||||
- **Lists**: Markdown lists → `ORDERED_LIST`/`BULLETED_LIST` nodes
|
||||
|
||||
### Example Conversion
|
||||
|
||||
**Markdown Input:**
|
||||
```markdown
|
||||
# Welcome to My Blog
|
||||
|
||||
This is a paragraph with some content.
|
||||
|
||||
## Features
|
||||
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
```
|
||||
|
||||
**Ricos JSON Output:**
|
||||
```json
|
||||
{
|
||||
"nodes": [
|
||||
{
|
||||
"type": "HEADING",
|
||||
"nodes": [{
|
||||
"type": "TEXT",
|
||||
"textData": {
|
||||
"text": "Welcome to My Blog",
|
||||
"decorations": []
|
||||
}
|
||||
}],
|
||||
"headingData": { "level": 1 }
|
||||
},
|
||||
{
|
||||
"type": "PARAGRAPH",
|
||||
"nodes": [{
|
||||
"type": "TEXT",
|
||||
"textData": {
|
||||
"text": "This is a paragraph with some content.",
|
||||
"decorations": []
|
||||
}
|
||||
}],
|
||||
"paragraphData": {}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
The integration includes comprehensive error handling for:
|
||||
|
||||
- **Authentication Errors**: Invalid tokens, expired sessions
|
||||
- **Permission Errors**: Insufficient Wix app permissions
|
||||
- **Content Errors**: Invalid content format, missing required fields
|
||||
- **Network Errors**: API timeouts, connection issues
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Token Storage**: Access and refresh tokens are stored securely
|
||||
2. **HTTPS**: All API calls use HTTPS in production
|
||||
3. **Scope Limitation**: Only requests necessary permissions
|
||||
4. **Token Refresh**: Automatic token refresh when expired
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **"Wix account not connected"**
|
||||
- Solution: Use the Wix Test Page to connect your account
|
||||
|
||||
2. **"Insufficient permissions"**
|
||||
- Solution: Reconnect your Wix account with proper permissions
|
||||
|
||||
3. **"Failed to import image"**
|
||||
- Solution: Check image URL accessibility and format
|
||||
|
||||
4. **"Content format error"**
|
||||
- Solution: Ensure content is valid markdown
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable debug logging by setting the log level to DEBUG in your environment:
|
||||
|
||||
```bash
|
||||
LOG_LEVEL=DEBUG
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
1. **Scheduled Publishing**: Support for scheduled blog posts
|
||||
2. **Bulk Publishing**: Publish multiple posts at once
|
||||
3. **Content Templates**: Pre-defined content templates for Wix
|
||||
4. **Analytics Integration**: Track published post performance
|
||||
5. **Advanced Formatting**: Support for more Ricos node types
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions about the Wix integration:
|
||||
|
||||
1. Check the troubleshooting section above
|
||||
2. Review the Wix API documentation
|
||||
3. Check the application logs for detailed error messages
|
||||
4. Contact the development team
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Wix REST API Documentation](https://dev.wix.com/docs/rest)
|
||||
- [Wix Blog API](https://dev.wix.com/docs/rest/business-solutions/blog)
|
||||
- [Wix OAuth 2.0](https://dev.wix.com/docs/rest/app-management/oauth-2)
|
||||
- [Ricos JSON Format](https://dev.wix.com/docs/ricos/api-reference/ricos-document)
|
||||
Reference in New Issue
Block a user