Base code
This commit is contained in:
Kunthawat Greethong
254
docs-site/docs/user-journeys/developers/integration-guide.md
Normal file
254
docs-site/docs/user-journeys/developers/integration-guide.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# Integration Guide - Developers
|
||||
|
||||
This guide will help you integrate ALwrity into your existing applications and workflows using our comprehensive API.
|
||||
|
||||
## 🎯 What You'll Accomplish
|
||||
|
||||
By the end of this guide, you'll have:
|
||||
- ✅ Connected ALwrity to your application
|
||||
- ✅ Set up basic content generation workflows
|
||||
- ✅ Implemented webhooks for real-time updates
|
||||
- ✅ Created custom integrations with your tools
|
||||
|
||||
## ⏱️ Time Required: 1-2 hours
|
||||
|
||||
## 🚀 Step-by-Step Integration
|
||||
|
||||
### Step 1: API Authentication Setup (15 minutes)
|
||||
|
||||
#### Get Your API Key
|
||||
1. **Access ALwrity Dashboard** - Log into your ALwrity instance
|
||||
2. **Navigate to API Settings** - Go to Settings → API Keys
|
||||
3. **Generate API Key** - Create a new API key for your application
|
||||
4. **Test Connection** - Verify your API key works
|
||||
|
||||
#### Basic Authentication
|
||||
```bash
|
||||
# Test your API connection
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||||
https://your-alwrity-instance.com/api/health
|
||||
```
|
||||
|
||||
#### Rate Limiting
|
||||
- **Standard Limit**: 100 requests per hour
|
||||
- **Burst Limit**: 20 requests per minute
|
||||
- **Best Practice**: Implement retry logic with exponential backoff
|
||||
|
||||
### Step 2: Core API Integration (30 minutes)
|
||||
|
||||
#### Content Generation API
|
||||
ALwrity provides several content generation endpoints:
|
||||
|
||||
**Blog Content Generation**
|
||||
```python
|
||||
# Generate a blog post
|
||||
response = requests.post('https://your-instance.com/api/blog-writer',
|
||||
headers={'Authorization': 'Bearer YOUR_API_KEY'},
|
||||
json={
|
||||
'topic': 'AI in Marketing',
|
||||
'keywords': ['AI', 'marketing', 'automation'],
|
||||
'target_audience': 'marketing professionals',
|
||||
'length': 'long_form'
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
**Social Media Content**
|
||||
```python
|
||||
# Generate LinkedIn post
|
||||
response = requests.post('https://your-instance.com/api/linkedin-writer',
|
||||
headers={'Authorization': 'Bearer YOUR_API_KEY'},
|
||||
json={
|
||||
'topic': 'Content Strategy Tips',
|
||||
'hashtags': ['#ContentStrategy', '#Marketing'],
|
||||
'tone': 'professional'
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
#### SEO Analysis API
|
||||
```python
|
||||
# Analyze content for SEO
|
||||
response = requests.post('https://your-instance.com/api/seo-analyzer',
|
||||
headers={'Authorization': 'Bearer YOUR_API_KEY'},
|
||||
json={
|
||||
'content': 'Your content here...',
|
||||
'target_keywords': ['keyword1', 'keyword2']
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Step 3: Webhook Integration (20 minutes)
|
||||
|
||||
#### Set Up Webhooks
|
||||
Webhooks allow ALwrity to notify your application when content generation is complete.
|
||||
|
||||
**Webhook Configuration**
|
||||
1. **Create Webhook Endpoint** - Set up an endpoint in your application
|
||||
2. **Register Webhook** - Add your webhook URL in ALwrity settings
|
||||
3. **Verify Signature** - Always verify webhook signatures for security
|
||||
|
||||
**Example Webhook Handler**
|
||||
```python
|
||||
@app.route('/webhook/alwrity', methods=['POST'])
|
||||
def handle_webhook():
|
||||
# Verify webhook signature
|
||||
signature = request.headers.get('X-ALWRITY-Signature')
|
||||
if not verify_signature(request.data, signature):
|
||||
return 'Unauthorized', 401
|
||||
|
||||
data = request.json
|
||||
|
||||
if data['event_type'] == 'content_generated':
|
||||
# Handle content generation completion
|
||||
process_generated_content(data['content'])
|
||||
|
||||
return 'OK', 200
|
||||
```
|
||||
|
||||
#### Available Webhook Events
|
||||
- **content_generated**: Content generation completed
|
||||
- **seo_analysis_complete**: SEO analysis finished
|
||||
- **research_complete**: Research phase completed
|
||||
- **user_action**: User interactions with your integration
|
||||
|
||||
### Step 4: Custom Workflow Integration (25 minutes)
|
||||
|
||||
#### Content Pipeline Integration
|
||||
Create automated workflows that combine multiple ALwrity features:
|
||||
|
||||
**Basic Content Pipeline**
|
||||
1. **Research Phase** - Gather insights about the topic
|
||||
2. **Outline Generation** - Create content structure
|
||||
3. **Content Creation** - Generate the actual content
|
||||
4. **SEO Optimization** - Analyze and improve SEO
|
||||
|
||||
**Example Workflow**
|
||||
```python
|
||||
def create_content_pipeline(topic, keywords):
|
||||
# Step 1: Research
|
||||
research = alwrity_client.research(topic, keywords)
|
||||
|
||||
# Step 2: Generate outline
|
||||
outline = alwrity_client.generate_outline(topic, research)
|
||||
|
||||
# Step 3: Create content
|
||||
content = alwrity_client.generate_blog_content(topic, outline)
|
||||
|
||||
# Step 4: SEO analysis
|
||||
seo_analysis = alwrity_client.analyze_seo(content, keywords)
|
||||
|
||||
return {
|
||||
'content': content,
|
||||
'seo_score': seo_analysis['score'],
|
||||
'suggestions': seo_analysis['suggestions']
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 Platform-Specific Integrations
|
||||
|
||||
### WordPress Integration
|
||||
**Plugin Development**
|
||||
- Use ALwrity API to generate content for WordPress posts
|
||||
- Integrate with WordPress editor for seamless content creation
|
||||
- Add custom meta fields for SEO optimization
|
||||
|
||||
**Key Features**
|
||||
- One-click content generation
|
||||
- SEO optimization suggestions
|
||||
- Content templates and variations
|
||||
|
||||
### Shopify Integration
|
||||
**App Development**
|
||||
- Generate product descriptions automatically
|
||||
- Create marketing content for product pages
|
||||
- Optimize content for e-commerce SEO
|
||||
|
||||
**Use Cases**
|
||||
- Product description generation
|
||||
- Marketing email content
|
||||
- Social media posts for products
|
||||
|
||||
### Slack Integration
|
||||
**Bot Development**
|
||||
- Generate content directly in Slack channels
|
||||
- Share content creation tasks with team members
|
||||
- Get content suggestions and ideas
|
||||
|
||||
**Commands**
|
||||
- `/alwrity blog [topic]` - Generate blog content
|
||||
- `/alwrity social [platform] [topic]` - Create social media content
|
||||
- `/alwrity seo [content]` - Analyze SEO
|
||||
|
||||
## 🎯 Best Practices
|
||||
|
||||
### Error Handling
|
||||
- **Always implement retry logic** for API calls
|
||||
- **Handle rate limiting** gracefully
|
||||
- **Validate API responses** before processing
|
||||
- **Log errors** for debugging and monitoring
|
||||
|
||||
### Performance Optimization
|
||||
- **Cache frequently used data** to reduce API calls
|
||||
- **Use batch processing** for multiple content requests
|
||||
- **Implement async processing** for better performance
|
||||
- **Monitor API usage** to stay within limits
|
||||
|
||||
### Security
|
||||
- **Never expose API keys** in client-side code
|
||||
- **Use environment variables** for sensitive data
|
||||
- **Verify webhook signatures** for security
|
||||
- **Implement proper authentication** for your endpoints
|
||||
|
||||
## 🚀 Common Use Cases
|
||||
|
||||
### Content Management Systems
|
||||
- **Automated blog posting** with ALwrity-generated content
|
||||
- **SEO optimization** for existing content
|
||||
- **Content scheduling** and publishing workflows
|
||||
|
||||
### Marketing Automation
|
||||
- **Email campaign content** generation
|
||||
- **Social media posting** automation
|
||||
- **Landing page content** creation
|
||||
|
||||
### E-commerce Platforms
|
||||
- **Product description** generation
|
||||
- **Marketing content** for product launches
|
||||
- **SEO optimization** for product pages
|
||||
|
||||
## 🆘 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
- **API Key Invalid**: Verify your API key is correct and active
|
||||
- **Rate Limit Exceeded**: Implement proper rate limiting and retry logic
|
||||
- **Webhook Not Working**: Check webhook URL and signature verification
|
||||
- **Content Quality Issues**: Adjust parameters like tone, length, and target audience
|
||||
|
||||
### Getting Help
|
||||
- **Check API Documentation** for detailed endpoint information
|
||||
- **Review Error Messages** for specific issue details
|
||||
- **Contact Support** for technical assistance
|
||||
- **Join Community** for peer support and best practices
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
### Immediate Actions (This Week)
|
||||
1. **Set up API authentication** and test connectivity
|
||||
2. **Implement basic content generation** in your application
|
||||
3. **Set up webhook endpoints** for real-time updates
|
||||
4. **Test your integration** with sample data
|
||||
|
||||
### This Month
|
||||
1. **Build custom workflows** using ALwrity APIs
|
||||
2. **Implement error handling** and monitoring
|
||||
3. **Create platform-specific integrations** for your use case
|
||||
4. **Optimize performance** and add caching
|
||||
|
||||
## 🚀 Ready for More?
|
||||
|
||||
**[Learn about advanced usage →](advanced-usage.md)**
|
||||
|
||||
---
|
||||
|
||||
*Questions? [Join our community](https://github.com/AJaySi/ALwrity/discussions) or [contact support](mailto:support@alwrity.com)!*
|
||||
Reference in New Issue
Block a user