diff --git a/src/data/nav/platform.ts b/src/data/nav/platform.ts index 5a6dc1abf8..ae12a3a71e 100644 --- a/src/data/nav/platform.ts +++ b/src/data/nav/platform.ts @@ -238,9 +238,46 @@ export default { pages: [ { name: 'Overview', - link: '/docs/account', + link: '/docs/platform/account', index: true, }, + { + name: 'Dashboard', + pages: [ + { + name: 'Dashboard overview', + link: '/docs/platform/account/dashboard', + }, + { + name: 'Dashboard guide', + link: '/docs/platform/account/dashboard-guide', + }, + { + name: 'Your account', + link: '/docs/platform/account/your-account', + }, + { + name: 'Account settings', + link: '/docs/platform/account/account-settings', + }, + { + name: 'Limits', + link: '/docs/platform/account/limits', + }, + { + name: 'Usage', + link: '/docs/platform/account/usage', + }, + { + name: 'My Settings', + link: '/docs/platform/account/my-settings', + }, + { + name: 'My Access Tokens', + link: '/docs/platform/account/my-access-tokens', + }, + ], + }, { name: 'User management', link: '/docs/platform/account/users', @@ -277,21 +314,29 @@ export default { name: 'API keys', link: '/docs/platform/account/app/api', }, + { + name: 'Integrations', + link: '/docs/platform/account/app/integrations', + }, { name: 'Queues', - link: '/docs/platform/account/app/queues', + link: '/docs/platform/account/app/app-queues', }, { name: 'Notifications', - link: '/docs/platform/account/app/notifications', + link: '/docs/platform/account/app/app-notifications', }, { name: 'Dev console', - link: '/docs/platform/account/app/console', + link: '/docs/platform/account/app/dev-console', + }, + { + name: 'CLI testing', + link: '/docs/platform/account/app/cli-testing', }, { name: 'Settings', - link: '/docs/platform/account/app/settings', + link: '/docs/platform/account/app/app-settings', }, ], }, diff --git a/src/pages/docs/channels/options/encryption.mdx b/src/pages/docs/channels/options/encryption.mdx index 554150a58d..dff7fed1f1 100644 --- a/src/pages/docs/channels/options/encryption.mdx +++ b/src/pages/docs/channels/options/encryption.mdx @@ -32,7 +32,7 @@ Unencrypted communication with Ably is **disallowed** if any of the following co * You attempt to use [Basic Authentication](/docs/auth/basic) and thus transmit a private API key over an unencrypted connection. You are only permitted to use unencrypted connections with [Token Authentication](/docs/auth/token) as tokens expire, limiting the impact of token interception. -* You have specified that TLS is required in your [app settings](/docs/platform/account/app/settings). +* You have specified that TLS is required in your [app settings](/docs/platform/account/app/app-settings). * A client using an unencrypted connection attempts to attach to a channel that is configured to be used with [TLS only](/docs/channels#rules). diff --git a/src/pages/docs/platform/account/2fa.mdx b/src/pages/docs/platform/account/2fa.mdx index 57ee9560f6..c437ebc0c2 100644 --- a/src/pages/docs/platform/account/2fa.mdx +++ b/src/pages/docs/platform/account/2fa.mdx @@ -13,13 +13,13 @@ Two-factor authentication (2FA) is an authentication process requiring users to To enable 2FA for your own user login: 1. Log in to your [account](https://ably.com/accounts/any). -2. Select **My Settings** from the account navigation dropdown. -3. Toggle **Enable Two-Factor Authentication** under the **Two-factor authentication** section. +2. Select My Settings from the account navigation dropdown. +3. Toggle Enable Two-Factor Authentication under the Two-factor authentication section. * Re-enter your password as prompted. -4. Select your **Country**. -5. Enter your **Phone number** -6. Click **Next** to receive an SMS with a security token. -7. Enter the security token and click **Verify security code**. +4. Select your Country. +5. Enter your Phone number +6. Click Next to receive an SMS with a security token. +7. Enter the security token and click Verify security code. 8. Scan the QR code into an authenticator app such as Authy, or Google Authenticator. 9. Store your recovery codes in a safe location. @@ -28,8 +28,8 @@ To enable 2FA for your own user login: To disable 2FA for your own user login: 1. Log in to your [account](https://ably.com/accounts/any). -2. Select **My Settings** from the account navigation dropdown. -3. Click the **Disable Two-Factor Authentication** button. +2. Select My Settings from the account navigation dropdown. +3. Click the Disable Two-Factor Authentication button. * Re-enter your password as prompted. ### Change phone number @@ -51,15 +51,15 @@ The account owner must already have 2FA enabled for their own login before they To enforce 2FA for all users: 1. Log in to your [account](https://ably.com/accounts/any). -2. Select **Settings** from the account navigation dropdown. -3. Toggle **Require Two-Factor Authentication for all account users** under the **Authentication Settings** section. -4. **Save** the authentication settings. +2. Select Settings from the account navigation dropdown. +3. Toggle Require Two-Factor Authentication for all account users under the Authentication Settings section. +4. Save the authentication settings. ### Remove 2FA requirement of all users To remove the requirement for all users to authenticate with 2FA: 1. Log in to your [account](https://ably.com/accounts/any). -2. Select **Settings** from the account navigation dropdown. -3. Toggle **Require Two-Factor Authentication for all account users** under the **Authentication Settings** section. -4. **Save** the authentication settings. +2. Select Settings from the account navigation dropdown. +3. Toggle Require Two-Factor Authentication for all account users under the Authentication Settings section. +4. Save the authentication settings. diff --git a/src/pages/docs/platform/account/account-settings.mdx b/src/pages/docs/platform/account/account-settings.mdx new file mode 100644 index 0000000000..c76efc0a64 --- /dev/null +++ b/src/pages/docs/platform/account/account-settings.mdx @@ -0,0 +1,144 @@ +--- +title: Account settings +meta_description: "Configure your Ably account settings, preferences, and account-level options through the dashboard interface." +meta_keywords: "Ably account settings, account configuration, account preferences, account management" +redirect_from: + - /docs/account/account-settings +--- + +Configure your Ably account settings, preferences, and account-level options through the dashboard interface. + +Account settings allow you to customize your Ably account behavior and configure account-wide preferences that affect your entire organization. + +## Accessing account settings + +To manage your account settings: + +1. Click Account in the top navigation bar +2. Select Settings from the dropdown menu +3. You'll be taken to the account settings page + +## Account configuration options + +### Basic account information + +Configure fundamental account details: + +| Setting | Description | +| ------- | ----------- | +| Account name | Display name for your organization | +| Account description | Optional description of your account purpose | +| Time zone | Default time zone for timestamps and reports | +| Contact information | Primary contact details for the account | + +### Account preferences + +Customize account-wide behavior: + +| Preference | Description | +| ---------- | ----------- | +| Default notification settings | Account-level notification preferences | +| Data retention policies | How long to retain various types of data | +| Regional preferences | Regional settings and compliance options | +| Display preferences | Default dashboard and interface settings | + +### Security settings + +Configure account-level security options: + +| Security Option | Description | +| --------------- | ----------- | +| Two-factor authentication | Require 2FA for all account users | +| IP address restrictions | Limit access to specific IP ranges | +| Session timeout | Configure automatic logout timeouts | +| Login notifications | Email alerts for account access | + +## Managing account settings + +### Updating basic information + +To modify account details: + +1. Navigate to the account settings page +2. Locate the "Basic Information" section +3. Click Edit next to the setting you want to change +4. Update the information as needed +5. Click Save to apply changes + +### Configuring preferences + +To adjust account preferences: + +1. Find the "Preferences" section in account settings +2. Review current settings and their impacts +3. Modify preferences according to your needs +4. Ensure changes align with your organization's requirements +5. Save your updated preferences + +### Security configuration + +To enhance account security: + +1. Access the "Security" section of account settings +2. Review current security policies +3. Enable appropriate security features for your organization +4. Configure settings to match your security requirements +5. Test security settings to ensure they work as expected + +## Account settings best practices + +### Regular review + +- Periodically review account settings to ensure they remain appropriate +- Update contact information when organizational changes occur +- Review security settings annually or when security requirements change + +### Documentation + +- Keep track of account setting changes and their rationale +- Document security policies and settings for compliance purposes +- Maintain records of who makes changes and when + +### Team coordination + +- Ensure account settings align with your team's workflow needs +- Communicate setting changes that may affect team members +- Consider the impact of account settings on all users + +### Security considerations + +- Enable two-factor authentication for enhanced security +- Regularly review and update IP restrictions as needed +- Monitor login notifications for unauthorized access attempts +- Keep security settings aligned with organizational policies + +## Common account setting tasks + +### Setting up notifications + +Configure how your account receives important notifications: + +1. Navigate to notification preferences +2. Choose which events trigger notifications +3. Select delivery methods (email, dashboard alerts) +4. Set notification frequency and timing + +### Configuring data policies + +Establish data handling preferences: + +1. Review data retention options +2. Configure automatic data cleanup policies +3. Set compliance-related data handling preferences +4. Ensure policies meet regulatory requirements + +### Managing regional settings + +Configure regional compliance and preferences: + +1. Select appropriate regional data handling +2. Configure compliance settings for your jurisdiction +3. Set regional display preferences +4. Ensure settings meet local requirements + +Account settings provide the foundation for how your Ably account operates and integrates with your organization's policies and procedures. \ No newline at end of file diff --git a/src/pages/docs/platform/account/app/api.mdx b/src/pages/docs/platform/account/app/api.mdx index 2421063578..4ce2570319 100644 --- a/src/pages/docs/platform/account/app/api.mdx +++ b/src/pages/docs/platform/account/app/api.mdx @@ -16,7 +16,7 @@ Before setting up multiple API keys with different permissions or sharing API ke The following steps create a new API Key: -* Click **Create a new API key**. +* Click Create a new API key. * Assign a friendly name. * Give the new API key a descriptive name (e.g. chat app key) so it is easy to identify later. @@ -28,14 +28,14 @@ To manage an API key: set [capabilities](/docs/auth/capabilities), define resour | Capability | Description | | ---------- | ----------- | -| **Publish** | Allow clients to publish messages to channels. | -| **Subscribe** | Allow clients to receive messages and presence state changes. | -| **History** | Allow clients to retrieve message and presence history. | -| **Presence** | Allow clients to register presence on a channel. | -| **Channel metadata** | Allow clients to query channel metadata. | -| **Push admin and push-subscribe** | Allow clients to manage and subscribe to push notifications. | -| **Statistics** | Allow clients to query usage statistics. | -| **Privileged headers** | Allow clients to set privileged headers, such as to skip channel rules. | +| Publish | Allow clients to publish messages to channels. | +| Subscribe | Allow clients to receive messages and presence state changes. | +| History | Allow clients to retrieve message and presence history. | +| Presence | Allow clients to register presence on a channel. | +| Channel metadata | Allow clients to query channel metadata. | +| Push admin and push-subscribe | Allow clients to manage and subscribe to push notifications. | +| Statistics | Allow clients to query usage statistics. | +| Privileged headers | Allow clients to set privileged headers, such as to skip channel rules. | ### Set resource restrictions @@ -64,4 +64,4 @@ A single API key cannot support complex permission combinations, such as publish ### Change your API key settings -Click **Settings** on the required API key to change its settings. The same settings apply as when creating a new API key. +Click Settings on the required API key to change its settings. The same settings apply as when creating a new API key. diff --git a/src/pages/docs/platform/account/app/app-notifications.mdx b/src/pages/docs/platform/account/app/app-notifications.mdx new file mode 100644 index 0000000000..85d17d2e3d --- /dev/null +++ b/src/pages/docs/platform/account/app/app-notifications.mdx @@ -0,0 +1,389 @@ +--- +title: Notifications +meta_description: "Configure and manage push notifications for your Ably application to deliver messages to mobile devices and web browsers." +meta_keywords: "Ably push notifications, mobile push, web push, notification configuration, device registration" +redirect_from: + - /docs/account/app/notifications +--- + +Configure and manage push notifications for your Ably application to deliver messages to mobile devices and web browsers. + +Push notifications enable your application to reach users even when they're not actively using your app, providing critical updates and real-time alerts. + +## Accessing notification management + +To manage push notifications for your application: + +1. Navigate to your application dashboard +2. Click the Notifications tab +3. Configure push notification settings and test delivery + +## Push notification overview + +### What are push notifications + +Push notifications allow you to: + +- Reach inactive users - Send messages when your app isn't running +- Deliver critical updates - Ensure important information reaches users +- Re-engage users - Bring users back to your application +- Provide real-time alerts - Notify users of time-sensitive events + +### Supported platforms + +Ably supports push notifications for: + +| Platform | Service | Description | +| -------- | ------- | ----------- | +| iOS | Apple Push Notification service (APNs) | Native iOS applications | +| Android | Firebase Cloud Messaging (FCM) | Android applications and Chrome browsers | +| Web | Web Push API | Modern web browsers | +| React Native | Platform-specific | Cross-platform mobile applications | + +### Notification flow + +The push notification process: + +1. Device registration - Devices register for push notifications +2. Channel subscription - Devices subscribe to specific channels +3. Message publishing - Messages are published with push payloads +4. Notification delivery - Push services deliver to registered devices +5. User interaction - Users receive and can interact with notifications + +## Setting up push notifications + +### Platform configuration + +Configure push notifications for each platform: + +#### iOS (APNs) setup + +Configure Apple Push Notifications: + +| Setting | Description | +| ------- | ----------- | +| APNs key | Authentication key from Apple Developer account | +| Key ID | Identifier for your APNs key | +| Team ID | Apple Developer team identifier | +| Bundle ID | Your iOS application bundle identifier | +| Environment | Development or production APNs environment | + +#### Android (FCM) setup + +Configure Firebase Cloud Messaging: + +| Setting | Description | +| ------- | ----------- | +| Server key | Firebase server key for authentication | +| Sender ID | Firebase project sender identifier | +| Project ID | Google Cloud project identifier | +| Service account | Optional service account for enhanced security | + +#### Web Push setup + +Configure web push notifications: + +| Setting | Description | +| ------- | ----------- | +| VAPID keys | Voluntary Application Server Identification keys | +| Subject | Contact information (email or URL) | +| Public key | VAPID public key for client registration | +| Private key | VAPID private key for server authentication | + +### Notification credentials + +Securely store push notification credentials: + +1. Upload platform-specific certificates or keys +2. Configure authentication settings +3. Test connectivity to push services +4. Verify credentials are working correctly + +## Device registration + +### Registering devices + +Devices must register to receive push notifications: + + +```javascript +// iOS device registration example +const deviceDetails = { + id: 'device-unique-id', + platform: 'ios', + formFactor: 'phone', + metadata: { + deviceType: 'iPhone12,1' + } +}; + +const recipient = { + deviceToken: 'apns-device-token', + deviceId: 'device-unique-id' +}; + +await ably.push.admin.deviceRegistrations.save(deviceDetails, recipient); +``` + + +### Device management + +Manage registered devices: + +| Operation | Description | +| --------- | ----------- | +| Register | Add new device for push notifications | +| Update | Modify device details or token | +| Unregister | Remove device from push notifications | +| List | View all registered devices | +| Get details | Retrieve specific device information | + +### Device metadata + +Store relevant device information: + +- Device identifiers - Unique device and user IDs +- Platform details - Operating system and version +- Application version - For compatibility and targeting +- User preferences - Notification settings and categories + +## Channel subscriptions + +### Subscribing devices to channels + +Connect devices to specific channels for targeted notifications: + + +```javascript +// Subscribe device to channel +await ably.push.admin.channelSubscriptions.save({ + channel: 'news-updates', + deviceId: 'device-unique-id' +}); +``` + + +### Subscription management + +Manage channel subscriptions: + +| Operation | Description | +| --------- | ----------- | +| Subscribe | Add device to channel notifications | +| Unsubscribe | Remove device from channel notifications | +| List subscriptions | View device's channel subscriptions | +| List devices | See all devices subscribed to a channel | + +### Subscription patterns + +Common subscription strategies: + +- User-based - Subscribe devices belonging to specific users +- Topic-based - Subscribe to content categories or interests +- Geographic - Subscribe based on location or region +- Role-based - Subscribe based on user roles or permissions + +## Publishing push notifications + +### Creating push payloads + +Publish messages with push notification data: + + +```javascript +// Publish with push notification +await channel.publish('news-update', { + title: 'Breaking News', + content: 'Important news content here' +}, { + push: { + notification: { + title: 'Breaking News Alert', + body: 'Tap to read important news update' + }, + data: { + newsId: '12345', + category: 'breaking' + } + } +}); +``` + + +### Platform-specific payloads + +Customize notifications for each platform: + +#### iOS notification format + +```json +{ + "aps": { + "alert": { + "title": "Notification Title", + "body": "Notification message" + }, + "badge": 1, + "sound": "default" + }, + "custom": "data" +} +``` + +#### Android notification format + +```json +{ + "notification": { + "title": "Notification Title", + "body": "Notification message", + "icon": "ic_notification" + }, + "data": { + "custom": "data" + } +} +``` + +### Notification targeting + +Control who receives notifications: + +| Targeting Method | Description | +| ---------------- | ----------- | +| Channel-based | All devices subscribed to a channel | +| Device-specific | Specific device tokens or IDs | +| User-based | All devices belonging to specific users | +| Conditional | Based on device metadata or user attributes | + +## Testing push notifications + +### Push inspector tool + +Use the built-in testing tool: + +1. Device testing - Send test notifications to specific devices +2. Channel testing - Test notifications for channel subscribers +3. Payload testing - Verify notification format and content +4. Delivery tracking - Monitor test notification delivery + +### Testing checklist + +Verify push notification functionality: + +| Test | Description | +| ---- | ----------- | +| Device registration | Confirm devices can register successfully | +| Channel subscription | Verify subscription and unsubscription work | +| Notification delivery | Test message delivery to registered devices | +| Payload formatting | Ensure notifications display correctly | +| Platform compatibility | Test across different devices and OS versions | + +### Debugging common issues + +| Issue | Possible Cause | Solution | +| ----- | -------------- | -------- | +| Notifications not delivered | Invalid device tokens | Check device registration status | +| Wrong notification format | Platform-specific payload errors | Verify payload structure | +| Authentication failures | Invalid push credentials | Check APNs/FCM configuration | +| Delivery delays | Push service issues | Monitor push service status | + +## Monitoring push notifications + +### Delivery metrics + +Track push notification performance: + +| Metric | Description | +| ------ | ----------- | +| Delivery rate | Percentage of notifications successfully delivered | +| Bounce rate | Failed deliveries due to invalid tokens | +| Open rate | Users who opened the notification | +| Click-through rate | Users who acted on the notification | + +### Analytics dashboard + +Monitor push notification analytics: + +- Delivery statistics - Success and failure rates +- Device metrics - Active vs. inactive device counts +- Channel performance - Subscription and engagement rates +- Platform breakdown - Performance across iOS, Android, and web + +### Delivery tracking + +Track individual notification delivery: + +- Delivery status - Sent, delivered, failed states +- Failure reasons - Why notifications failed to deliver +- Timing metrics - Time from publish to delivery +- User interactions - Opens, clicks, and dismissals + +## Push notification best practices + +### User experience + +Design effective notifications: + +- Clear messaging - Use concise, actionable text +- Appropriate timing - Send at relevant times for users +- Personalization - Customize content for individual users +- Frequency management - Avoid notification fatigue + +### Technical best practices + +Implement notifications effectively: + +- Token management - Keep device tokens current and valid +- Error handling - Gracefully handle delivery failures +- Batch operations - Efficiently manage large device lists +- Security - Protect user data and notification content + +### Privacy and permissions + +Respect user privacy: + +- Permission requests - Ask for notification permissions appropriately +- Opt-out options - Provide easy unsubscribe mechanisms +- Data minimization - Collect only necessary device information +- Transparency - Clearly explain notification purposes + +### Performance optimization + +Optimize notification delivery: + +- Efficient targeting - Send only to relevant users +- Payload optimization - Minimize notification data size +- Connection pooling - Optimize push service connections +- Rate limiting - Respect push service limits + +## Advanced notification features + +### Rich notifications + +Enhance notification content: + +- Images and media - Include photos, videos, or audio +- Action buttons - Add interactive elements +- Custom layouts - Design platform-specific interfaces +- Deep linking - Direct users to specific app content + +### Scheduled notifications + +Plan notification delivery: + +- Time-based sending - Schedule for optimal user times +- Timezone awareness - Send at appropriate local times +- Recurring notifications - Set up regular notification patterns +- Conditional delivery - Send based on user activity or context + +### A/B testing + +Optimize notification effectiveness: + +- Content testing - Compare different message variations +- Timing experiments - Find optimal send times +- Frequency testing - Determine ideal notification rates +- Audience segmentation - Test different approaches for user groups + +Push notifications provide powerful user engagement capabilities, enabling you to maintain connections with users and deliver timely, relevant information across multiple platforms. \ No newline at end of file diff --git a/src/pages/docs/platform/account/app/app-queues.mdx b/src/pages/docs/platform/account/app/app-queues.mdx new file mode 100644 index 0000000000..fb8a1dcd1b --- /dev/null +++ b/src/pages/docs/platform/account/app/app-queues.mdx @@ -0,0 +1,279 @@ +--- +title: Queues +meta_description: "Configure and manage message queues for your Ably application to ensure reliable message processing and delivery." +meta_keywords: "Ably queues, message queues, reliable messaging, queue configuration, message processing" +redirect_from: + - /docs/account/app/queues +--- + +Configure and manage message queues for your Ably application to ensure reliable message processing and delivery. + +Message queues provide reliable, ordered message delivery with durability guarantees, perfect for critical business processes and workflows. + +## Accessing queue management + +To manage queues for your application: + +1. Navigate to your application dashboard +2. Click the Queues tab +3. View existing queues and create new ones + +## Understanding Ably queues + +### What are message queues + +Ably queues provide: + +- Reliable delivery - Messages are persisted until successfully processed +- Ordered processing - Messages are delivered in the order they were published +- Durability - Messages survive network issues and service restarts +- Scalable processing - Multiple consumers can process messages in parallel + +### Queue vs. channels + +Key differences between queues and channels: + +| Feature | Channels | Queues | +| ------- | -------- | ------ | +| Delivery guarantee | At most once | At least once | +| Message persistence | Temporary (minutes to hours) | Until processed | +| Processing model | Pub/Sub (broadcast) | Point-to-point (single consumer) | +| Ordering | No guarantee | First-in-first-out (FIFO) | +| Use case | Real-time updates | Reliable workflows | + +### Queue architecture + +Queues consist of: + +- Publishers - Applications that send messages to queues +- Queue storage - Persistent storage for unprocessed messages +- Consumers - Applications that receive and process messages +- Dead letter handling - Management of failed messages + +## Queue configuration + +### Creating a new queue + +To create a queue: + +1. Click Create new queue on the queues page +2. Configure queue settings: + - Queue name - Unique identifier for the queue + - Region - Geographic location for optimal performance + - Message TTL - How long messages remain in the queue + - Max length - Maximum number of messages to store + - Dead letter policy - How to handle failed messages + +### Queue settings + +| Setting | Description | Options | +| ------- | ----------- | ------- | +| Name | Unique queue identifier | Alphanumeric with dashes/underscores | +| Region | Geographic placement | us-east-1, eu-west-1, ap-southeast-1, etc. | +| TTL (Time To Live) | Message expiration time | 1 minute to 14 days | +| Max length | Queue capacity limit | 1 to 10,000 messages | +| Dead letter queue | Failed message handling | Enable/disable with retry limits | + +### Dead letter queues + +Configure handling for failed messages: + +- Retry attempts - How many times to retry failed messages +- Dead letter destination - Where failed messages are moved +- Failure reasons - Track why messages failed processing +- Recovery options - Ability to reprocess dead letter messages + +## Publishing to queues + +### Publishing messages + +Send messages to queues using the REST API: + + +```bash +curl -X POST https://rest.ably.io/queues/your-queue-name/messages \ + -H "Authorization: Basic YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"name": "event-name", "data": {"key": "value"}}' +``` + + +### Message format + +Queue messages include: + +| Field | Description | Required | +| ----- | ----------- | -------- | +| name | Event name or message type | No | +| data | Message payload | Yes | +| id | Unique message identifier | No (auto-generated) | +| timestamp | Message creation time | No (auto-generated) | + +### Publishing patterns + +Common publishing approaches: + +- Direct publishing - Send messages directly to queues +- Channel to queue - Route channel messages to queues via rules +- Batch publishing - Send multiple messages in a single request +- Conditional publishing - Publish based on specific conditions + +## Consuming from queues + +### Setting up consumers + +Configure message consumption: + +1. Consumer endpoint - URL that receives messages +2. Authentication - Headers for secure message delivery +3. Concurrency - Number of parallel message deliveries +4. Retry policy - How to handle delivery failures + +### Consumer configuration + +| Setting | Description | +| ------- | ----------- | +| Endpoint URL | HTTPS URL that receives queue messages | +| HTTP method | Request method (typically POST) | +| Headers | Authentication and custom headers | +| Timeout | Maximum time to wait for response | +| Concurrent deliveries | Number of parallel message sends | + +### Message acknowledgment + +Handle message processing confirmation: + +- Automatic acknowledgment - Messages acknowledged on successful HTTP response +- Manual acknowledgment - Explicit confirmation required +- Negative acknowledgment - Reject messages for retry +- Processing timeouts - Automatic retry after timeout + +### Consumer best practices + +Design effective consumers: + +- Idempotent processing - Handle duplicate message delivery safely +- Fast processing - Minimize processing time to improve throughput +- Error handling - Distinguish between temporary and permanent failures +- Monitoring - Track consumer health and performance + +## Queue monitoring + +### Queue metrics + +Monitor queue performance: + +| Metric | Description | +| ------ | ----------- | +| Queue length | Number of messages waiting for processing | +| Message rate | Messages published and consumed per second | +| Processing latency | Time from publish to successful consumption | +| Error rate | Percentage of failed message deliveries | +| Consumer status | Health and availability of message consumers | + +### Monitoring dashboard + +The queue dashboard shows: + +- Real-time metrics - Current queue state and activity +- Historical data - Trends over time for capacity planning +- Alert thresholds - Warnings for unusual queue behavior +- Consumer health - Status of configured message consumers + +### Setting up alerts + +Configure notifications for: + +- Queue length thresholds - When queues become too full +- Consumer failures - When message delivery fails repeatedly +- Processing delays - When message latency exceeds thresholds +- Dead letter accumulation - When failed messages pile up + +## Queue management operations + +### Scaling queues + +Manage queue capacity: + +- Increase max length - Allow more messages in the queue +- Add consumers - Increase processing capacity +- Regional distribution - Use multiple queues across regions +- Load balancing - Distribute messages across multiple queues + +### Queue maintenance + +Regular maintenance tasks: + +- Monitor queue length - Ensure queues don't become overwhelmed +- Review dead letter messages - Investigate and resolve failures +- Update consumer endpoints - Maintain healthy message processing +- Optimize queue settings - Adjust TTL and capacity based on usage + +### Queue cleanup + +Manage old or failed messages: + +- Purge messages - Clear all messages from a queue +- Delete expired messages - Remove messages past their TTL +- Reprocess dead letters - Retry failed messages after fixes +- Archive old queues - Remove unused queues to reduce clutter + +## Advanced queue patterns + +### Queue chaining + +Connect multiple queues for complex workflows: + +1. Primary processing - Initial message handling +2. Secondary processing - Additional workflow steps +3. Final processing - Completion and cleanup +4. Error handling - Failed message recovery + +### Priority queues + +Implement message prioritization: + +- Multiple queues - Separate queues for different priorities +- Consumer routing - Direct consumers to process high-priority first +- Message tagging - Include priority information in messages +- Dynamic routing - Route based on message content or source + +### Queue patterns for reliability + +Design for high reliability: + +- Duplicate detection - Handle duplicate messages gracefully +- Message ordering - Maintain processing order when required +- Failure isolation - Prevent failed messages from blocking others +- Recovery procedures - Plan for queue and consumer failures + +## Troubleshooting common issues + +### Queue performance problems + +| Issue | Cause | Solution | +| ----- | ----- | -------- | +| Growing queue length | Consumer too slow or down | Scale consumers or fix consumer issues | +| High message latency | Queue overloaded | Add more consumers or optimize processing | +| Message delivery failures | Consumer endpoint problems | Check endpoint health and configuration | +| Dead letter accumulation | Permanent processing errors | Investigate and fix root cause | + +### Consumer issues + +Common consumer problems: + +- Authentication failures - Verify consumer endpoint credentials +- Timeout errors - Increase timeout or optimize processing +- HTTP errors - Check consumer endpoint implementation +- Network issues - Verify connectivity and DNS resolution + +### Message processing errors + +Handle processing failures: + +- Temporary failures - Implement retry with exponential backoff +- Permanent failures - Move to dead letter queue for investigation +- Duplicate processing - Design idempotent message handlers +- Ordering violations - Ensure single-threaded processing when order matters + +Message queues provide reliable, durable message processing capabilities that complement Ably's real-time pub/sub messaging for building robust, scalable applications. \ No newline at end of file diff --git a/src/pages/docs/platform/account/app/app-settings.mdx b/src/pages/docs/platform/account/app/app-settings.mdx new file mode 100644 index 0000000000..a1d0635989 --- /dev/null +++ b/src/pages/docs/platform/account/app/app-settings.mdx @@ -0,0 +1,325 @@ +--- +title: App settings +meta_description: "Configure your Ably application settings, channel rules, security options, and protocol support through the dashboard interface." +meta_keywords: "Ably app settings, application configuration, channel rules, security settings, protocol support" +redirect_from: + - /docs/account/app/settings +--- + +Configure your Ably application settings, channel rules, security options, and protocol support through the dashboard interface. + +Application settings control how your Ably app behaves, including security policies, channel rules, and protocol compatibility options. + +## Accessing app settings + +To configure your application settings: + +1. Navigate to your application dashboard +2. Click the Settings tab +3. Modify configuration options as needed + +## Basic application settings + +### Application information + +Configure fundamental app details: + +| Setting | Description | +| ------- | ----------- | +| App ID | Unique identifier assigned by Ably (read-only) | +| Name | Human-readable name for your application | +| Description | Optional description of the application's purpose | +| Status | Enable or disable the entire application | + +### Application status + +Control application availability: + +| Status | Effect | +| ------ | ------ | +| Enabled | Application accepts connections and processes messages | +| Disabled | All connections rejected, no message processing | + +When disabling an application: +- Existing connections are immediately terminated +- New connection attempts are rejected +- Message publishing and subscription stop working +- API operations return authentication errors + +## Security settings + +### Transport Layer Security (TLS) + +Configure encryption requirements: + +| Setting | Description | +| ------- | ----------- | +| TLS required | Force all connections to use encrypted transport | +| TLS optional | Allow both encrypted and unencrypted connections | + +Recommendation: Always require TLS for production applications to protect data in transit. + +### Authentication requirements + +Set authentication policies: + +| Policy | Description | +| ------ | ----------- | +| API key required | All connections must provide valid API key | +| Token authentication | Require JWT tokens for client authentication | +| Anonymous access | Allow unauthenticated connections (not recommended) | + +### Access control + +Configure client access restrictions: + +- Client ID requirements - Force clients to identify themselves +- Capability restrictions - Limit what operations clients can perform +- IP address filtering - Restrict access to specific IP ranges +- Geographic restrictions - Limit access by country or region + +## Channel configuration + +### Default channel settings + +Configure default behavior for all channels: + +| Setting | Description | +| ------- | ----------- | +| Message persistence | How long to store messages by default | +| Presence events | Enable presence functionality by default | +| Message history | Allow message history retrieval | +| Push notifications | Enable push notification capabilities | + +### Channel rules + +Create specific rules for channels or channel namespaces: + +#### Creating channel rules + +1. Click Add new rule in the channel rules section +2. Configure rule parameters: + - Channel pattern - Which channels this rule applies to + - Rule settings - Specific behavior for matching channels + - Priority - Order of rule evaluation + +#### Channel rule settings + +| Setting | Description | Options | +| ------- | ----------- | ------- | +| Channel filter | Pattern to match channel names | Exact name or regex pattern | +| Persist messages | Message storage duration | None, 2 minutes, 24 hours, 72 hours | +| Persist last message | Keep last message for 365 days | Enabled/disabled | +| Identified clients only | Require client ID for access | Enabled/disabled | +| TLS only | Force encrypted connections | Enabled/disabled | +| Push notifications | Enable push capabilities | Enabled/disabled | +| Message interactions | Enable message threading/reactions | Enabled/disabled | +| Server-side batching | Batch messages for efficiency | Enabled/disabled | + +#### Rule examples + +Common channel rule patterns: + + +``` +// Private channels require identification +Pattern: private:* +Settings: Identified clients only = true, TLS only = true + +// Admin channels with extended persistence +Pattern: admin:* +Settings: Persist messages = 72 hours, Identified clients only = true + +// Public channels with basic persistence +Pattern: public:* +Settings: Persist messages = 2 minutes, Push notifications = true +``` + + +### Message persistence + +Configure how long messages are stored: + +| Duration | Use Case | +| -------- | -------- | +| None | Real-time only, no history needed | +| 2 minutes | Basic connection recovery | +| 24 hours | Short-term message replay | +| 72 hours | Extended message history | +| 365 days (last message) | Maintaining channel state | + +## Protocol support + +### Supported protocols + +Enable compatibility with different messaging protocols: + +| Protocol | Description | Use Case | +| -------- | ----------- | -------- | +| Ably native | Full-featured Ably protocol | Best performance and features | +| Pusher | Pusher protocol compatibility | Migrate from Pusher | +| PubNub | PubNub protocol compatibility | Migrate from PubNub | +| MQTT | MQTT protocol support | IoT and embedded devices | + +### Protocol configuration + +For each enabled protocol: + +- Authentication mapping - How API keys map to protocol auth +- Feature limitations - Which features are available +- Message format - How messages are formatted +- Connection parameters - Protocol-specific settings + +### Migration considerations + +When enabling protocol compatibility: + +- Test thoroughly - Verify protocol behavior matches expectations +- Feature parity - Some Ably features may not be available +- Performance - Native protocol typically performs better +- Security - Ensure security requirements are met + +## Application limits + +### Configuring limits + +Set application-specific limits: + +| Limit Type | Description | +| ---------- | ----------- | +| Connection limit | Maximum concurrent connections | +| Message rate limit | Messages per second/minute/hour | +| Channel limit | Maximum concurrent channels | +| Presence limit | Maximum presence members per channel | + +### Rate limiting + +Configure rate limiting policies: + +- Per-connection limits - Limits applied to individual connections +- Per-channel limits - Limits applied to specific channels +- Global limits - Limits applied across the entire application +- Burst allowances - Temporary exceeding of normal limits + +### Limit enforcement + +When limits are exceeded: + +- Connection throttling - Slow down new connections +- Message queuing - Queue excess messages for later delivery +- Rejection - Reject excess requests with error responses +- Client notification - Inform clients of rate limiting + +## Webhook configuration + +### Webhook rules + +Configure webhooks to send events to external services: + +| Event Type | Description | +| ---------- | ----------- | +| Channel lifecycle | Channel attach/detach events | +| Message events | Published messages | +| Presence events | Presence enter/leave/update | +| Connection events | Client connect/disconnect | + +### Webhook settings + +For each webhook rule: + +| Setting | Description | +| ------- | ----------- | +| URL | Endpoint to receive webhook data | +| Events | Which events trigger the webhook | +| Channel filter | Limit to specific channels | +| Headers | Custom HTTP headers for authentication | +| Retry policy | How to handle failed deliveries | + +## Advanced configuration + +### Custom domains + +Configure custom domain for your application: + +- CNAME setup - Point your domain to Ably +- SSL certificates - Secure connections to your domain +- Regional endpoints - Geographic optimization +- Load balancing - Distribute traffic across regions + +### Regional configuration + +Optimize for specific geographic regions: + +- Primary region - Main data center for your application +- Failover regions - Backup regions for redundancy +- Data residency - Keep data in specific jurisdictions +- Latency optimization - Route traffic to nearest region + +### Compliance settings + +Configure for regulatory compliance: + +- Data retention policies - Automatic data cleanup +- Audit logging - Track all administrative actions +- Encryption at rest - Secure stored data +- Regional data handling - Comply with local laws + +## Managing application settings + +### Updating settings + +To modify application settings: + +1. Navigate to the specific settings section +2. Make desired changes +3. Click Save to apply changes +4. Monitor application for any impact + +### Settings validation + +Before saving settings changes: + +- Impact assessment - Understand how changes affect existing connections +- Compatibility check - Ensure changes don't break existing clients +- Testing - Test changes in development before applying to production +- Rollback plan - Know how to revert changes if needed + +### Change monitoring + +After updating settings: + +- Connection monitoring - Watch for authentication failures +- Error rate tracking - Monitor for increased error rates +- Performance impact - Check for latency or throughput changes +- Client feedback - Monitor for user-reported issues + +## Application settings best practices + +### Security hardening + +Implement robust security: + +- Always require TLS for production applications +- Use strong authentication - Require client identification +- Implement least privilege - Give clients minimal necessary capabilities +- Regular review - Audit settings periodically + +### Performance optimization + +Optimize application performance: + +- Appropriate persistence - Use only necessary message storage +- Efficient channel rules - Avoid overly broad or complex patterns +- Rate limiting - Prevent abuse while allowing legitimate usage +- Regional optimization - Configure for your user base geography + +### Operational considerations + +Design for operational efficiency: + +- Documentation - Keep records of settings and their purposes +- Change management - Have procedures for settings changes +- Monitoring - Track the impact of configuration changes +- Backup - Maintain backups of critical configurations + +Application settings provide fine-grained control over your Ably application's behavior, enabling you to optimize performance, security, and functionality for your specific use case. \ No newline at end of file diff --git a/src/pages/docs/platform/account/app/cli-testing.mdx b/src/pages/docs/platform/account/app/cli-testing.mdx new file mode 100644 index 0000000000..535d49fa6d --- /dev/null +++ b/src/pages/docs/platform/account/app/cli-testing.mdx @@ -0,0 +1,555 @@ +--- +title: CLI testing +meta_description: "Use the Ably CLI for comprehensive testing of your application's real-time functionality from the command line, including automated testing scenarios." +meta_keywords: "Ably CLI testing, command line testing, automated testing, real-time testing, CLI tools" +redirect_from: + - /docs/account/app/cli +--- + +Use the Ably CLI for comprehensive testing of your application's real-time functionality from the command line, enabling automated testing scenarios and development workflows. + +The CLI testing tools complement the dashboard's dev console by providing scriptable, automated testing capabilities that integrate with your development and CI/CD processes. + +## Accessing CLI testing + +To use CLI testing for your application: + +1. Install and configure the Ably CLI +2. Authenticate with your Ably account +3. Select your application for testing +4. Run testing commands and scenarios + +## Setting up CLI testing + +### Installation and authentication + +Install the Ably CLI and authenticate: + + +```shell +# Install Ably CLI globally +npm install -g @ably/cli + +# Login and authenticate +ably login + +# List your apps +ably apps list + +# Switch to your app +ably apps switch +``` + + +### Configuration verification + +Verify your setup before testing: + + +```shell +# Check current app and API key +ably status + +# Test basic connectivity +ably channels list +``` + + +## Testing methodologies + +### Interactive testing + +Test functionality interactively from the command line: + +#### Message testing + +Test message publishing and subscription: + + +```shell +# Subscribe to a channel (run in one terminal) +ably channels subscribe test-channel + +# Publish messages (run in another terminal) +ably channels publish test-channel "Hello World" + +# Publish multiple messages +ably channels publish --count 5 test-channel "Message {{.Count}}" + +# Publish with event name +ably channels publish test-channel --name "user-joined" "User data" +``` + + +#### Presence testing + +Test presence functionality: + + +```shell +# Enter presence +ably channels presence enter test-channel --client-id user1 --data '{"status": "online"}' + +# Subscribe to presence events +ably channels presence subscribe test-channel + +# Update presence data +ably channels presence update test-channel --data '{"status": "away"}' + +# Leave presence +ably channels presence leave test-channel +``` + + +### Automated testing scenarios + +Create automated test scripts for common scenarios: + +#### Connection reliability testing + +Test connection stability and recovery: + + +```shell +#!/bin/bash +# Test connection recovery + +echo "Testing connection reliability..." + +# Subscribe to channel in background +ably channels subscribe reliability-test & +SUBSCRIBE_PID=$! + +# Publish messages at intervals +for i in {1..10}; do + ably channels publish reliability-test "Test message $i" + sleep 2 +done + +# Clean up +kill $SUBSCRIBE_PID +echo "Connection test complete" +``` + + +#### Load testing + +Test performance under load: + + +```shell +#!/bin/bash +# Simple load testing script + +CHANNEL="load-test-channel" +MESSAGE_COUNT=100 +CONCURRENT_PUBLISHERS=5 + +echo "Starting load test: $MESSAGE_COUNT messages with $CONCURRENT_PUBLISHERS publishers" + +# Function to publish messages +publish_messages() { + local publisher_id=$1 + for i in $(seq 1 $((MESSAGE_COUNT / CONCURRENT_PUBLISHERS))); do + ably channels publish $CHANNEL "Publisher $publisher_id - Message $i" + done +} + +# Start concurrent publishers +for i in $(seq 1 $CONCURRENT_PUBLISHERS); do + publish_messages $i & +done + +# Wait for all publishers to complete +wait +echo "Load test complete" +``` + + +#### Integration testing + +Test integration points: + + +```shell +#!/bin/bash +# Integration testing script + +APP_NAME="my-app" +TEST_CHANNEL="integration-test" + +echo "Starting integration tests for $APP_NAME" + +# Test 1: Basic connectivity +echo "Test 1: Basic connectivity" +if ably channels list > /dev/null 2>&1; then + echo "✓ Connectivity test passed" +else + echo "✗ Connectivity test failed" + exit 1 +fi + +# Test 2: Message publishing +echo "Test 2: Message publishing" +if ably channels publish $TEST_CHANNEL "Integration test message" > /dev/null 2>&1; then + echo "✓ Message publishing test passed" +else + echo "✗ Message publishing test failed" + exit 1 +fi + +# Test 3: Channel history +echo "Test 3: Channel history" +if ably channels history $TEST_CHANNEL --limit 1 > /dev/null 2>&1; then + echo "✓ Channel history test passed" +else + echo "✗ Channel history test failed" + exit 1 +fi + +echo "All integration tests passed" +``` + + +## Advanced testing features + +### Chat testing + +Test chat functionality using CLI: + + +```shell +# List chat rooms +ably chat rooms list + +# Send chat messages +ably chat messages send room-1 "Hello chat!" + +# Subscribe to chat messages +ably chat messages subscribe room-1 + +# Test typing indicators +ably chat typing start room-1 --client-id user1 +ably chat typing stop room-1 --client-id user1 + +# Test message reactions +ably chat reactions send room-1 message-id --reaction "👍" +``` + + +### Spaces testing + +Test collaborative spaces: + + +```shell +# List spaces +ably spaces list + +# Enter a space +ably spaces members enter workspace-1 --client-id user1 + +# Set member location +ably spaces locations set workspace-1 --x 100 --y 200 + +# Set cursor position +ably spaces cursors set workspace-1 --x 150 --y 175 + +# Acquire a lock +ably spaces locks acquire workspace-1 --lock-id "document-1" +``` + + +### Statistics and monitoring + +Monitor application performance via CLI: + + +```shell +# Get app statistics +ably apps stats --start-time "2024-01-01" --end-time "2024-01-02" + +# Monitor live statistics +ably apps stats --live + +# Check account usage +ably accounts stats + +# Monitor logs in real-time +ably logs subscribe +``` + + +## Testing best practices + +### Test organization + +Structure your CLI tests effectively: + +| Practice | Description | +| -------- | ----------- | +| Script organization | Create dedicated test scripts for different scenarios | +| Environment separation | Use different apps for development, testing, and production | +| Test isolation | Ensure tests don't interfere with each other | +| Cleanup procedures | Remove test data after test completion | + +### Automated testing integration + +Integrate CLI testing into your development workflow: + +#### CI/CD integration + +Add CLI tests to your CI/CD pipeline: + + +```yaml +# GitHub Actions example +name: Ably CLI Tests +on: [push, pull_request] + +jobs: + cli-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Install Node.js + uses: actions/setup-node@v3 + with: + node-version: '18' + + - name: Install Ably CLI + run: npm install -g @ably/cli + + - name: Authenticate with Ably + run: ably auth --token ${{ secrets.ABLY_CLI_TOKEN }} + + - name: Run CLI integration tests + run: ./scripts/run-cli-tests.sh +``` + + +#### Local development testing + +Create development testing scripts: + + +```shell +#!/bin/bash +# dev-test.sh - Development testing script + +set -e + +echo "Running development tests..." + +# Switch to development app +ably apps switch dev-app-id + +# Run quick smoke tests +./tests/smoke-tests.sh + +# Run feature tests +./tests/feature-tests.sh + +echo "Development tests completed successfully" +``` + + +### Performance testing + +Use CLI for performance analysis: + +#### Latency testing + +Measure message delivery latency: + + +```shell +#!/bin/bash +# Latency testing script + +CHANNEL="latency-test" +ITERATIONS=10 + +echo "Testing message latency..." + +for i in $(seq 1 $ITERATIONS); do + START_TIME=$(date +%s%N) + ably channels publish $CHANNEL "Latency test $i" --wait + END_TIME=$(date +%s%N) + + LATENCY=$((($END_TIME - $START_TIME) / 1000000)) + echo "Message $i latency: ${LATENCY}ms" +done +``` + + +#### Throughput testing + +Test message throughput capabilities: + + +```shell +#!/bin/bash +# Throughput testing + +CHANNEL="throughput-test" +DURATION=60 # seconds +MESSAGE_SIZE=1024 # bytes + +echo "Starting throughput test for ${DURATION} seconds..." + +# Generate test message of specified size +TEST_MESSAGE=$(printf '%*s' $MESSAGE_SIZE | tr ' ' 'A') + +START_TIME=$(date +%s) +MESSAGE_COUNT=0 + +while [ $(($(date +%s) - START_TIME)) -lt $DURATION ]; do + ably channels publish $CHANNEL "$TEST_MESSAGE" > /dev/null 2>&1 + MESSAGE_COUNT=$((MESSAGE_COUNT + 1)) +done + +THROUGHPUT=$((MESSAGE_COUNT / DURATION)) +echo "Throughput: $THROUGHPUT messages/second" +``` + + +## Debugging with CLI + +### Connection debugging + +Debug connection issues using CLI tools: + + +```shell +# Check connection status +ably status + +# Test connectivity with different environments +ably channels list --environment sandbox +ably channels list --environment production + +# Debug authentication issues +ably auth status +ably auth refresh +``` + + +### Message debugging + +Debug message delivery problems: + + +```shell +# Check channel activity +ably channels list --active + +# Monitor message flow +ably channels subscribe debug-channel --verbose + +# Check message history +ably channels history debug-channel --limit 50 + +# Test with different message formats +ably channels publish debug-channel '{"type": "test", "data": "value"}' +``` + + +### Error handling testing + +Test error conditions and recovery: + + +```shell +#!/bin/bash +# Error handling test script + +echo "Testing error handling scenarios..." + +# Test invalid channel names +ably channels subscribe "invalid channel name" 2>&1 | grep -q "error" && echo "✓ Invalid channel name handled" + +# Test unauthorized access +ORIGINAL_KEY=$(ably status | grep "API Key" | cut -d: -f2 | xargs) +ably auth set --api-key invalid-key +ably channels list 2>&1 | grep -q "unauthorized" && echo "✓ Unauthorized access handled" + +# Restore original key +ably auth set --api-key "$ORIGINAL_KEY" + +echo "Error handling tests complete" +``` + + +## CLI testing vs dashboard testing + +### When to use CLI testing + +CLI testing is ideal for: + +| Scenario | Advantage | +| -------- | --------- | +| Automated testing | Scriptable and repeatable test execution | +| CI/CD integration | Easy integration with build pipelines | +| Load testing | Generate high volumes of test traffic | +| Performance testing | Precise timing and measurement capabilities | +| Regression testing | Automated verification of functionality | + +### When to use dashboard testing + +Dashboard dev console is better for: + +| Scenario | Advantage | +| -------- | --------- | +| Visual debugging | Real-time visual feedback and monitoring | +| Interactive exploration | Point-and-click interface for ad-hoc testing | +| Quick prototyping | Rapid testing of ideas without scripting | +| Team collaboration | Shared visual interface for team members | +| Real-time monitoring | Live dashboard view of application activity | + +### Combined approach + +Use both CLI and dashboard testing together: + +1. Use dashboard for initial development and debugging +2. Create CLI scripts for repetitive test scenarios +3. Integrate CLI tests into automated testing pipelines +4. Use dashboard to investigate issues found by CLI tests + +## Troubleshooting CLI testing + +### Common issues and solutions + +| Issue | Cause | Solution | +| ----- | ----- | -------- | +| Authentication failures | Expired or invalid tokens | Run `ably login` to re-authenticate | +| Connection timeouts | Network or service issues | Check network connectivity and service status | +| Permission errors | Insufficient API key capabilities | Verify API key permissions in dashboard | +| Script failures | Environment or dependency issues | Validate CLI installation and environment setup | + +### Diagnostic commands + +Use these commands for troubleshooting: + + +```shell +# Check CLI version and status +ably version +ably status + +# Test basic connectivity +ably ping + +# Validate authentication +ably auth validate + +# Check app configuration +ably apps show + +# Test API key capabilities +ably api-keys show +``` + + +CLI testing provides powerful automation capabilities that complement the dashboard's interactive tools, enabling comprehensive testing strategies for your Ably applications. \ No newline at end of file diff --git a/src/pages/docs/platform/account/app/console.mdx b/src/pages/docs/platform/account/app/console.mdx deleted file mode 100644 index aec15bb350..0000000000 --- a/src/pages/docs/platform/account/app/console.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Dev console -meta_description: "Gain realtime insights into application-wide events, such as connection status changes, channel activity, and event logs.” -meta_keywords: “Ably dev console, realtime monitoring, connection status changes, channel activity, event logs" -redirect_from: - - /docs/account/app/console ---- - -The dev console tab provides realtime insights into application-wide events, such as connection status changes and channel activity. These features enable you to: - -* Observe changes in connection status across the application. -* View activity on specific channels, including message traffic and channel events. -* Examine event logs to troubleshoot your application. - -## Application-wide events interface - -The application-wide events interface allows you to monitor your application's health and activity in realtime. - -The following explains the realtime monitoring tools in the application-wide events interface: - -| Field | Description | -| ----- | ----------- | -| **API key** | The API key to access and view events within the app. | -| **Average application-wide events per second (p/s)** | This metric shows the average number of events occurring per second across your application. For example, if the current rate is 0, no active events are being processed. | -| **Event log table** | The event log table displays a record of events related to the current client's connection status. This table can be used to debug potential issues in your application. | - -## Message auditing and logging - -The dev console displays messages in realtime for debugging and testing purposes, but does not provide persistent message auditing or logging capabilities. Ably does not currently offer native functionality to view historical messages filtered by specific channels or client IDs for auditing purposes. - -If you need to audit or log messages by channel or client ID, implement this functionality on the application side. Consider using: - -- [Webhooks](/docs/platform/integrations/webhooks) to send message events to your logging system -- [Message queues](/docs/platform/integrations/queues) to process and store message data -- Client-side logging in your application code - -For native message auditing features, [contact support](mailto:support@ably.com) to discuss requirements. - -## Channels - -The following is a step-by-step instructions for connecting to a channel, publishing messages. - -### Connect to a channel - -The following explains how to connect to a channel: - -| Step | Action | -| ---- | ------ | -| **Enter a channel name** | In the channel name field, choose a name (e.g get-started). | -| **Attach to channel** | Click the **attach to channel** button. This connects you to the **get-started** channel, enabling you to start publishing or subscribing to messages. | -| **Monitor channel status** | The interface will display the channel status as **pending** and then **attached** once connected, confirming that the channel is ready for interaction.| - -### Publish a message - -The following explains how to publish a message: - -| Step | Action | -| ---- | ------ | -| **Message data** | In the **message data** field, type a message (e.g. example). | -| **Publish message** | Click the **publish message** button to send the message to the **get-started** channel. | -| **View the message** | If you have a subscriber , it will receive and display the message in the console. | - -The following explains how to interact with presence: - -| Step | Action | -| ---- | ------ | -| **Client ID** | Enter a unique client ID to simulate joining the presence of the channel. | -| **Enter presence** | Click **enter presence** to indicate that this client is now in the channel. | -| **Monitor presence** | The interface will list all clients in the channel under **presence members**. | - -### Control the channel - -The following explains how to control the channel in the dev console: - -| Step | Action | -| ---- | ------ | -| **Detach** | Click **detach** to disconnect from the channel. | -| **Pause** | Use **pause** to temporarily stop receiving messages. | -| **Clear** | Click **clear** to clear the channel data or logs from the interface. | diff --git a/src/pages/docs/platform/account/app/dev-console.mdx b/src/pages/docs/platform/account/app/dev-console.mdx new file mode 100644 index 0000000000..cfb68dcff4 --- /dev/null +++ b/src/pages/docs/platform/account/app/dev-console.mdx @@ -0,0 +1,382 @@ +--- +title: Dev console +meta_description: "Use the Ably dev console for real-time development, debugging, and testing of your application's messaging, presence, and connection features." +meta_keywords: "Ably dev console, debugging, real-time testing, development tools, message testing" +redirect_from: + - /docs/account/app/console +--- + +Use the Ably dev console for real-time development, debugging, and testing of your application's messaging, presence, and connection features. + +The dev console provides interactive tools for testing your Ably integration, debugging connection issues, and monitoring real-time activity during development. + +## Accessing the dev console + +To use the development console: + +1. Navigate to your application dashboard +2. Click the **Dev console** tab +3. Use the interactive tools for testing and debugging + +## Console overview + +### Development tools available + +The dev console provides: + +| Tool | Purpose | +| ---- | ------- | +| Connection tester | Establish and test connections to Ably | +| Message publisher | Send test messages to channels | +| Message subscriber | Receive and monitor channel messages | +| Presence manager | Enter, leave, and monitor presence | +| Channel inspector | View channel state and activity | +| Event logger | Monitor all events in real-time | + +### Real-time monitoring + +The console shows live data for: + +- Active connections - Current connections to your application +- Message activity - Messages flowing through channels +- Presence events - Users entering and leaving channels +- Channel lifecycle - Channel attachments and detachments +- Error events - Connection and message errors + +### Console interface + +The dev console interface includes: + +- Connection status - Shows current connection state +- Channel selector - Choose which channel to work with +- Message composer - Create and send test messages +- Event feed - Real-time stream of all activity +- Presence panel - Current presence members and states + +## Testing connections + +### Establishing connections + +Test connection functionality: + +1. **Select API key** - Choose which API key to use for testing +2. **Configure options** - Set client ID and connection parameters +3. **Connect** - Establish connection to Ably +4. Monitor status - Watch connection state changes + +### Connection parameters + +Configure test connections: + +| Parameter | Description | +| --------- | ----------- | +| API key | Which API key to use for authentication | +| Client ID | Identifier for the test client | +| Connection options | Additional connection parameters | +| Transport | Preferred connection transport method | + +### Connection states + +Monitor connection lifecycle: + +| State | Description | +| ----- | ----------- | +| Connecting | Attempting to establish connection | +| Connected | Successfully connected to Ably | +| Disconnected | Connection lost or terminated | +| Failed | Connection attempt failed | +| Suspended | Temporarily interrupted connection | + +## Message testing + +### Publishing messages + +Send test messages through the console: + +1. **Select channel** - Choose target channel for messages +2. **Compose message** - Enter event name and data +3. **Publish** - Send the message +4. Monitor delivery - Watch for delivery confirmation + +### Message composition + +Create test messages with: + +| Component | Description | +| --------- | ----------- | +| Event name | Optional name for the message event | +| Message data | Payload content (JSON, text, or binary) | +| Client ID | Override client ID for the message | +| Extras | Additional message metadata | + +### Message formats + +Test different message types: + + +```javascript +// Simple text message +{ + "name": "chat-message", + "data": "Hello, world!" +} + +// JSON data message +{ + "name": "user-update", + "data": { + "userId": 123, + "status": "online", + "location": "New York" + } +} + +// Binary data message +{ + "name": "file-chunk", + "data": "[binary data]", + "encoding": "base64" +} +``` + + +### Subscribing to messages + +Monitor channel activity: + +1. **Attach to channel** - Connect to specific channels +2. **Subscribe to events** - Listen for specific message types +3. **View messages** - See incoming messages in real-time +4. **Filter events** - Show only relevant message types + +## Presence testing + +### Managing presence + +Test presence functionality: + +| Action | Description | +| ------ | ----------- | +| Enter presence | Join a channel's presence set | +| Update presence | Modify presence data while present | +| Leave presence | Exit the channel's presence set | +| Get presence | Retrieve current presence members | + +### Presence data + +Include custom data with presence: + + +```javascript +// Enter presence with custom data +{ + "status": "available", + "location": "Office", + "activity": "Working on project" +} + +// Update presence data +{ + "status": "busy", + "activity": "In meeting" +} +``` + + +### Monitoring presence events + +Track presence activity: + +| Event Type | Description | +| ---------- | ----------- | +| Enter | Member joins presence | +| Update | Member updates presence data | +| Leave | Member leaves presence | +| Present | Initial presence state when subscribing | + +## Channel management + +### Channel operations + +Test channel functionality: + +| Operation | Description | +| --------- | ----------- | +| Attach | Connect to a channel | +| Detach | Disconnect from a channel | +| Subscribe | Listen for messages on a channel | +| Unsubscribe | Stop listening for messages | +| Get history | Retrieve past messages | + +### Channel states + +Monitor channel lifecycle: + +| State | Description | +| ----- | ----------- | +| Initialized | Channel created but not attached | +| Attaching | Attempting to attach to channel | +| Attached | Successfully attached to channel | +| Detaching | Disconnecting from channel | +| Detached | No longer connected to channel | +| Failed | Attachment failed | + +### Channel options + +Configure channel behavior: + +| Option | Description | +| ------ | ----------- | +| Persist messages | Store messages for history retrieval | +| Presence subscribe | Automatically subscribe to presence events | +| Delta compression | Enable delta compression for efficiency | +| Cipher key | Encrypt channel messages | + +## Event monitoring + +### Real-time event feed + +The console displays all events: + +- Message events - Published and received messages +- Presence events - Presence enter, update, and leave +- Connection events - Connection state changes +- Channel events - Channel attach, detach, and errors +- Error events - All error conditions and failures + +### Event filtering + +Filter events by type: + +| Filter | Shows | +| ------ | ----- | +| Messages | Only message publish and receive events | +| Presence | Only presence-related events | +| Connections | Only connection state changes | +| Channels | Only channel lifecycle events | +| Errors | Only error and failure events | + +### Event details + +Each event displays: + +- Timestamp - When the event occurred +- Event type - Category of event +- Channel - Which channel the event relates to +- Client ID - Which client generated the event +- Data - Event payload and metadata +- Status - Success or failure indication + +## Debugging tools + +### Connection debugging + +Diagnose connection issues: + +| Tool | Purpose | +| ---- | ------- | +| Connection logs | Detailed connection attempt information | +| Transport fallback | See which transports are attempted | +| Authentication debugging | Verify API key and token issues | +| Network diagnostics | Test network connectivity | + +### Message debugging + +Troubleshoot message issues: + +- Delivery confirmation - Verify messages are published successfully +- Subscription status - Check if clients are properly subscribed +- Message routing - Trace message path through the system +- Error analysis - Investigate failed message operations + +### Common debugging scenarios + +| Issue | Debugging Approach | +| ----- | ------------------ | +| Messages not received | Check subscription status and channel attachment | +| Connection failures | Review authentication and network connectivity | +| Presence not updating | Verify presence enter/update operations | +| Slow message delivery | Monitor connection quality and message size | + +## Development workflows + +### Testing new features + +Use the console to test new functionality: + +1. Plan test scenarios - Define what you want to test +2. Set up test data - Create appropriate test messages and presence +3. Execute tests - Run through scenarios step by step +4. Monitor results - Watch for expected behavior and errors +5. Document findings - Record issues and successful patterns + +### Integration debugging + +Debug application integration: + +1. Replicate issues - Use console to reproduce problems +2. Isolate variables - Test individual components separately +3. Compare behavior - Check console vs. application behavior +4. Identify root cause - Determine source of issues +5. Validate fixes - Test solutions using console + +### Performance testing + +Test application performance: + +- Message throughput - Send high-frequency test messages +- Connection stability - Test long-running connections +- Resource usage - Monitor memory and CPU impact +- Scalability limits - Test with multiple concurrent operations + +## Console best practices + +### Development workflow integration + +Incorporate console into development: + +- Regular testing - Use console throughout development process +- Feature validation - Test each new feature before deployment +- Debugging first - Check console before investigating code issues +- Documentation - Record successful test patterns for reuse + +### Security considerations + +Use console securely: + +- Test API keys - Use development keys, not production keys +- Sensitive data - Avoid testing with real user data +- Access control - Limit console access to development team +- Clean up - Remove test data and connections after testing + +### Efficiency tips + +Use console effectively: + +- Bookmark scenarios - Save useful test configurations +- Multiple tabs - Use separate tabs for different test scenarios +- History review - Check previous test results for patterns +- Automated testing - Use console patterns to build automated tests +- CLI integration - Combine console testing with CLI automation + +## Console vs CLI testing + +### When to use dev console + +The dev console is ideal for: + +- Interactive testing and debugging +- Visual real-time monitoring +- Quick prototyping and exploration +- Team collaboration and demonstration + +### When to use CLI testing + +CLI testing is better for: + +- Automated test scenarios +- CI/CD pipeline integration +- Performance and load testing +- Scripted testing workflows + +The dev console provides essential tools for developing, testing, and debugging real-time applications, helping you build robust integrations with Ably's platform. \ No newline at end of file diff --git a/src/pages/docs/platform/account/app/index.mdx b/src/pages/docs/platform/account/app/index.mdx index d782258986..ec5b2dcc47 100644 --- a/src/pages/docs/platform/account/app/index.mdx +++ b/src/pages/docs/platform/account/app/index.mdx @@ -12,7 +12,7 @@ Begin by [logging](https://ably.com/login) in to Ably through your browser. Once ## Create a new app -The following image displays the Ably dashboard when no apps have been created yet. To get started, you can easily **Create new app**: +The following image displays the Ably dashboard when no apps have been created yet. To get started, you can easily Create new app: ![Create apps in the Ably dashboard](../../../../../images/content/screenshots/dash/create-app.png) @@ -44,6 +44,21 @@ Your app dashboard provides the following tabs for monitoring and configuring yo ![Your app dashboard tabs](../../../../../images/content/screenshots/dash/dash-tabs.png) +The app dashboard provides the following tabs for monitoring and configuring your app: + +### Application dashboard tabs + +| Tab | Description | +| --- | ----------- | +| [Stats](/docs/platform/account/app/stats) | Monitor usage statistics, charts, and performance metrics | +| [API Keys](/docs/platform/account/app/api) | Create and manage API keys with specific capabilities | +| [Integrations](/docs/platform/account/app/integrations) | Configure webhooks and external service connections | +| [Queues](/docs/platform/account/app/app-queues) | Set up and manage message queues for reliable processing | +| [Notifications](/docs/platform/account/app/app-notifications) | Configure push notifications for mobile and web | +| [Dev console](/docs/platform/account/app/dev-console) | Real-time development and debugging tools | +| [CLI testing](/docs/platform/account/app/cli-testing) | Command-line testing and automation tools | +| [Settings](/docs/platform/account/app/app-settings) | Application configuration and channel rules | + ### Stats Monitor and analyze your app's performance through a [stats](/docs/platform/account/app/stats) table and chart: @@ -52,9 +67,6 @@ Monitor and analyze your app's performance through a [stats](/docs/platform/acco * Compare data over time to identify trends and optimize resources. * Adjust chart views with zoom options and set specific time ranges for detailed insights. -### Getting started - -Get started by connecting to Ably, and publishing your first message. ### API keys @@ -96,6 +108,15 @@ Monitor your application's health in realtime using Ably's [dev console](/docs/p * The event log table displays detailed records of connection events, which can be used for troubleshooting and diagnosing application issues. * Interact with Ably channels using command-line tools like cURL. +### CLI testing + +Automate testing and development workflows using Ably's [CLI testing](/docs/platform/account/app/cli-testing) tools: + +* Install and configure the Ably CLI for command-line interaction with your application. +* Create automated test scripts for message publishing, subscription, and presence testing. +* Integrate CLI testing into CI/CD pipelines for continuous integration workflows. +* Perform load testing and performance analysis using scriptable commands. + ### Settings Manage key aspects of your application [settings](/docs/platform/account/app/settings), including security, enabling or disabling the app, configuring rules for channels, and setting up protocol support for different SDKs: diff --git a/src/pages/docs/platform/account/app/integrations.mdx b/src/pages/docs/platform/account/app/integrations.mdx new file mode 100644 index 0000000000..d8bae24e3e --- /dev/null +++ b/src/pages/docs/platform/account/app/integrations.mdx @@ -0,0 +1,275 @@ +--- +title: Integrations +meta_description: "Configure webhooks, streaming integrations, and external service connections for your Ably application through the dashboard." +meta_keywords: "Ably integrations, webhooks, streaming, external services, integration configuration" +redirect_from: + - /docs/account/app/integrations +--- + +Configure webhooks, streaming integrations, and external service connections for your Ably application through the dashboard. + +Integrations allow your Ably application to send events to external systems and receive data from external sources, enabling powerful automation and data flow. + +## Accessing integrations + +To manage your application's integrations: + +1. Navigate to your application dashboard +2. Click the Integrations tab +3. Configure webhooks, streaming, and external connections + +## Types of integrations + +### Webhook integrations + +Send Ably events to external HTTP endpoints: + +| Webhook Type | Description | +| ------------ | ----------- | +| Channel lifecycle | Notify when channels are created, attached, or detached | +| Message events | Send published messages to external services | +| Presence events | Forward presence enter, leave, and update events | +| Connection events | Track client connections and disconnections | + +### Streaming integrations + +Stream Ably events to external platforms: + +| Platform | Description | +| -------- | ----------- | +| Amazon Kinesis | Real-time data streaming to AWS | +| Apache Kafka | High-throughput event streaming | +| Apache Pulsar | Cloud-native messaging system | +| Amazon SQS | Managed message queuing service | +| Google Pub/Sub | Global messaging and event ingestion | + +### Function integrations + +Process events through serverless functions: + +| Platform | Description | +| -------- | ----------- | +| AWS Lambda | Execute code in response to Ably events | +| Google Cloud Functions | Serverless event processing on Google Cloud | +| Azure Functions | Event-driven serverless compute on Azure | +| Cloudflare Workers | Edge computing for low-latency processing | + +## Setting up webhook integrations + +### Creating webhook rules + +To create a new webhook integration: + +1. Click Create new integration on the integrations page +2. Select Webhook as the integration type +3. Configure the webhook settings: + - Endpoint URL - Where to send the webhook data + - Event types - Which Ably events to include + - Channel filter - Limit to specific channels (optional) + - Headers - Custom HTTP headers for authentication + +### Webhook configuration options + +| Setting | Description | +| ------- | ----------- | +| URL | The endpoint that will receive webhook requests | +| Method | HTTP method (typically POST) | +| Headers | Custom headers for authentication or routing | +| Channel filter | Regular expression to match channel names | +| Event types | Specific events to include in the webhook | + +### Webhook security + +Secure your webhook endpoints: + +- Authentication headers - Include API keys or tokens +- Signature verification - Validate webhook authenticity +- HTTPS endpoints - Ensure encrypted data transmission +- IP whitelisting - Restrict access to known sources + +### Testing webhooks + +Verify webhook functionality: + +1. Test endpoint - Use the built-in testing tool +2. Monitor delivery - Check webhook delivery logs +3. Debug failures - Review error messages and retry attempts +4. Validate payloads - Ensure data format matches expectations + +## Configuring streaming integrations + +### Setting up streaming rules + +To create streaming integrations: + +1. Select Streaming from integration types +2. Choose your target platform (Kinesis, Kafka, etc.) +3. Configure connection details: + - Connection credentials - API keys or connection strings + - Target configuration - Stream names, topics, or queues + - Data formatting - Message format and serialization + - Filtering rules - Which events to stream + +### Platform-specific setup + +#### Amazon Kinesis integration + +Configure Kinesis streaming: + +| Setting | Description | +| ------- | ----------- | +| Region | AWS region for your Kinesis stream | +| Stream name | Target Kinesis stream | +| AWS credentials | Access key and secret for authentication | +| Partition key | How to partition data across shards | + +#### Apache Kafka integration + +Configure Kafka streaming: + +| Setting | Description | +| ------- | ----------- | +| Bootstrap servers | Kafka cluster connection points | +| Topic name | Target Kafka topic | +| Security protocol | Authentication method (SASL, SSL, etc.) | +| Serialization | Message format (JSON, Avro, etc.) | + +### Monitoring streaming integrations + +Track streaming performance: + +- Throughput metrics - Messages per second streamed +- Delivery rates - Success/failure ratios +- Latency monitoring - Time from Ably event to delivery +- Error tracking - Failed delivery attempts and causes + +## Managing integration rules + +### Rule configuration + +Each integration rule defines: + +| Component | Description | +| --------- | ----------- | +| Source | Which Ably events trigger the integration | +| Filter | Conditions that must be met for activation | +| Target | Where the event data is sent | +| Format | How the data is structured for delivery | + +### Channel filtering + +Control which channels trigger integrations: + +- All channels - Include events from any channel +- Specific channels - Exact channel name matches +- Pattern matching - Regular expressions for channel names +- Namespace filtering - Include/exclude channel namespaces + +### Event filtering + +Choose which events to include: + +| Event Category | Available Events | +| -------------- | ---------------- | +| Messages | Published messages with optional content filtering | +| Presence | Enter, leave, update presence events | +| Channels | Channel lifecycle events and occupancy changes | +| Connections | Client connection and disconnection events | + +## Integration best practices + +### Planning integrations + +Before implementing integrations: + +1. Map data flow - Understand how data moves between systems +2. Plan for scale - Consider volume and performance requirements +3. Design for reliability - Handle failures and retries gracefully +4. Consider latency - Balance real-time needs with system constraints + +### Security considerations + +Protect your integrations: + +- Secure endpoints - Use HTTPS and proper authentication +- Validate inputs - Check webhook payloads for malicious content +- Rate limiting - Prevent abuse of integration endpoints +- Monitor access - Track integration usage and access patterns + +### Performance optimization + +Optimize integration performance: + +- Batch processing - Group messages for efficiency where possible +- Selective filtering - Send only necessary events to reduce load +- Endpoint optimization - Ensure receiving systems can handle the load +- Monitor latency - Track and optimize end-to-end delivery times + +### Error handling + +Handle integration failures: + +- Retry policies - Configure automatic retry for failed deliveries +- Dead letter queues - Handle permanently failed messages +- Error alerting - Get notified of integration problems +- Fallback strategies - Plan alternative approaches for critical data + +## Monitoring and troubleshooting + +### Integration logs + +Track integration activity: + +- Delivery attempts - Success and failure records +- Response codes - HTTP status codes from endpoints +- Retry attempts - Failed delivery retry information +- Performance metrics - Latency and throughput data + +### Common issues and solutions + +| Issue | Cause | Solution | +| ----- | ----- | -------- | +| Delivery failures | Endpoint unavailable or misconfigured | Check endpoint health and configuration | +| Authentication errors | Invalid credentials or headers | Verify authentication details | +| Rate limiting | Too many requests to endpoint | Implement backoff or reduce frequency | +| Data format errors | Incorrect payload structure | Review and correct data formatting | + +### Performance monitoring + +Track key metrics: + +- Delivery success rate - Percentage of successful deliveries +- Average latency - Time from event to delivery +- Throughput capacity - Maximum events per second +- Error rates - Frequency and types of failures + +## Advanced integration scenarios + +### Multi-stage processing + +Chain integrations for complex workflows: + +1. Primary integration - Initial event processing +2. Secondary processing - Additional transformation or routing +3. Final destination - Ultimate data storage or action +4. Error handling - Manage failures at each stage + +### Conditional routing + +Route events based on content: + +- Content-based filtering - Route based on message data +- User-based routing - Different handling for different user types +- Geographic routing - Regional processing of events +- Time-based routing - Different handling based on time of day + +### Integration monitoring and alerting + +Set up comprehensive monitoring: + +- Health checks - Regular verification of integration status +- Performance alerts - Notifications for degraded performance +- Failure notifications - Immediate alerts for integration failures +- Capacity monitoring - Warnings for approaching limits + +Integrations enable powerful automation and data flow between Ably and your broader application ecosystem, supporting complex real-time architectures and business processes. \ No newline at end of file diff --git a/src/pages/docs/platform/account/app/notifications.mdx b/src/pages/docs/platform/account/app/notifications.mdx deleted file mode 100644 index a3da11ff9a..0000000000 --- a/src/pages/docs/platform/account/app/notifications.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Notifications -meta_description: Configure credentials for integrating Ably's push notification services with third-party services, send push notifications from the Ably dashboard, and inspect push notifications .” -meta_keywords: “Ably push notifications, configure FCM, configure APNS, Web Push setup, push inspector" -redirect_from: - - /docs/account/app/notifications ---- - -Before you can start using Ably's [push notification](/docs/push) services, you must configure the credentials for the third-party services you wish to integrate, such as FCM for Android devices, APNS for iOS devices, or Web Push for web browsers. - -### Configure FCM for Android devices - -* Go to the [Firebase Console.](https://firebase.google.com/) -* Click **add project** and follow the steps to **create and manage service account keys**. -* Download your service account **JSON file**. -* In your Ably [dashboard](https://ably.com/accounts), navigate to the **notifications** tab under your app settings. -* Go to **push notifications setup**, click **configure push**. -* Add your service account **JSON file** to the **setting up Firebase cloud messaging** section. - -### Configure APNs for iOS devices - -* Go to the [Apple Developer Program.](https://developer.apple.com/programs/) -* Use the Apple developer portal to create a **push notification** service certificate for your app. -* Export the certificate as a **.p12 file**. -* Next, you can either import the **.p12 cert** or create a **PEM file** and copy it into your Ably dashboard: - -* Import the **.p12 file**: - * In your Ably [dashboard](https://ably.com/accounts), navigate to the **Notifications** tab under your app settings. - * Go to **push notifications setup**, click **configure push** and scroll to the **setting up Apple push notification service** section. - * Select the **.p12 file** you exported and enter the password you created during the export process. - * Click **save**. You should receive confirmation that the certificate has been successfully imported. - * To further confirm the import, refresh the page and check if the **PEM cert** and **private key** text boxes are now populated with the imported key details. -* Create a **PEM file** from the **.p12 file**: - * Using [OpenSSL](https://www.openssl.org/), convert the recently exported **.p12 file** (`io.ably.test.p12`) to a **PEM file** with the following command: `$ openssl pkcs12 -in ./io.ably.test.p12 -out ./io.ably.test.pem -nodes -clcerts`. - * Open the **PEM file** in your text editor. - * Copy everything between and including `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`, and paste it into the **PEM cert** text box of the Apple push notification service section of your Ably notifications app [dashboard](https://ably.com/accounts). - * Similarly, copy everything between and including `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----`, and paste it into the **PEM private key** text box of the same section. Then, click **Save**. - -## Push inspector - -The Push inspector tool enables you to manually send push notifications by specifying the required data and notification fields. This tool helps test and debug your notification setup before going live. - -### API key - -The [API Key](/docs/platform/account/app/api) authenticates your requests when sending push notifications. Choose from the list of API keys associated with your Ably account. Each key has different permissions and scopes, so ensure you select the correct one for your notification tasks. - -### Push notification title and body - -Define the content of your push notification using the fields below: - -| Field | Purpose | How to Use | -| ----- | ------- | ---------- | -| Notification title | A title for the push notification, which will appear as the headline on the user's device. | Enter a short, clear title that captures the essence of the notification. | -| Notification body | The main content of the notification to be displayed below the title. | Write the key information or message that you want the user to read. | -| Notification data | Optional JSON data that the app can use for specific actions upon receiving the notification. | Include any extra data needed for app functionality, such as custom metadata or instructions. | - -### Push notification target - -Direct your push notifications to specific targets within the Ably platform. Select the appropriate target according to your notification strategy: - -| Target | Purpose | How to Use | -| ------ | ------- | ---------- | -| Channel name | Push notifications to all subscribers of a specific channel. | Enter the channel name and click push to channel to notify all devices subscribed to that channel. | -| Device ID | Send a notification directly to a specific device. | Enter the Device ID and click push to device to target a single device with the notification. | -| Client ID | Notify a specific client registered with Ably. | Enter the Client ID and click push to client to send the notification to the chosen client. | - -## Push inspector widget - -The Push Inspector widget allows you to monitor and manage your push notification infrastructure directly from the Ably dashboard. It provides insights into channel subscriptions, device registrations, and client registrations, making it easier to debug and optimize your notification setup. - -| Section | Purpose | How to Use | -| ------- | ------- | ---------- | -| Channel subscriptions | View and inspect all channels currently subscribed to push notifications. | Click inspect channel to see detailed information about a specific channel, including the number of subscribers and recent activity. | -| Device registrations | Access a list of all devices registered to receive push notifications. | Click inspect device to view detailed information about a specific device, such as its registration status, platform, and recent notifications. | -| Client registrations | Get an overview of all clients registered for push notifications within the Ably account. | Click inspect client ID to see detailed information about a specific client, including its subscriptions and recent activity. | diff --git a/src/pages/docs/platform/account/app/queues.mdx b/src/pages/docs/platform/account/app/queues.mdx deleted file mode 100644 index 82a351ebca..0000000000 --- a/src/pages/docs/platform/account/app/queues.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Queues -meta_description: Manage and configure Ably queues, monitor realtime data, and optimize performance.” -meta_keywords: “Ably Queues, realtime data, AMQP, STOMP, queue management, TTL, queue settings" -redirect_from: - - /docs/account/app/queues ---- - -Ably queues provide a way to consume realtime data using the [AMQP](/docs/platform/integrations/queues#consume-amqp) or [STOMP](/docs/platform/integrations/queues#consume-stomp) protocols. Find out more about using [Ably queues](/docs/platform/integrations/queues#what). - -## Manage your Ably queues - -The Ably queues tab enables you to: - -* Access a list of all your existing queues. -* Monitor realtime data flow and queue performance. -* Click on any queue to view and adjust its settings, such as TTL, maximum length, and region. - -### Provision a new queue - -When provisioning a new queue, you'll need to specify several things: - -| Field | Description | -| ----- | ----------- | -| **Name** | Choose a unique name for your queue. This will help you identify it within your dashboard and during application development. | -| **Region** | Select the geographic region where the queue will be hosted. This is important for optimizing latency and ensuring data residency aligns with your application's requirements. | -| **TTL (time to Live)** | Set the TTL, which determines how long messages remain in the queue before being automatically deleted if they are not consumed. The default account limit is 60 minutes. You can contact Ably support for assistance if you need a longer TTL. | -| **Max length** | Define the maximum number of messages the queue can hold at any given time. The default limit is 10,000 messages, but you can request an increase if your application requires more capacity. | - -### Set up queue rules - -Once you have provisioned a physical queue, you need to set up one or more queue rules to republish messages, presence events or channel events from pub/sub channels into a queue. Queue rules can either be used to publish to internal queues (hosted by Ably) or external external streams or queues (such as Amazon Kinesis and RabbitMQ). Publishing to external streams or queues is part of our [Ably Firehose servers](/docs/general/firehose). - -Ably queue rules are setup in the **Integrations** tab found within your app **dashboard**. Find out more about setting up [queue rules](/docs/platform/integrations/queues#setup). diff --git a/src/pages/docs/platform/account/app/settings.mdx b/src/pages/docs/platform/account/app/settings.mdx deleted file mode 100644 index c3091d00a7..0000000000 --- a/src/pages/docs/platform/account/app/settings.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Settings -meta_description: "Manage your Ably application settings including security, billing, authentication, and protocol support to optimize performance and enhance security." -meta_keywords: "Ably app settings, application management, security settings, two-factor authentication, billing management, protocol support, channel configuration, push notifications" -redirect_from: - - /docs/account/app/settings ---- - -Manage your Ably application settings including security, billing, authentication, and protocol support to optimize performance and enhance security. - -### Application settings overview - -The following provides an overview of your application settings. - -| Section | Description | -| ------ | ------------ | -| **App ID** | This ID is automatically generated by Ably when you create an application. It is a critical part of your application's identity and is included in every API key and token issued for your application. | -| **Name** | This is the user-defined name that you assigned when creating your application. It is helpful for quickly identifying the application among others in your dashboard, especially if you manage multiple applications. | -| **Security** | Enabled by default, this option enforces Transport Layer Security (TLS) for all connections to your application. TLS protocol ensures data encryption and secure communication between clients and servers. | -| **Enabled** | When an application is disabled, it no longer accepts new connections and deactivates all associated services. Clients cannot connect, send or receive messages, or use other Ably services. When enabled, the application allows new connections and activates all related services. | - -### Channel rule configuration - -The following explains the configuration rules for specific [namespaces](/docs/channels#namespaces) or [channels](/docs/channels): - -| Section | Description | -| ------- | ----------- | -| Namespace or channel ID | Identify the specific namespace or channel to which this rule will apply. | -| Persist last message | Stores the last message published on a channel for 365 days, accessible via the rewind mechanism. | -| Persist all messages | Ably stores all messages for two minutes by default. Depending on your account package, this can be increased to 24 or 72 hours. It is also possible to persist the last message sent to a channel for a year. | -| Identified | Requires clients to authenticate with a client ID to interact with channels in this namespace. | -| TLS only | Restricts access to channels within this namespace to clients connected using TLS. | -| Push notifications enabled | Enables publishing messages with a push payload, triggering native push notifications to registered devices. | -| Message interactions enabled | Enables unique time serial fields in messages, enabling typed references between messages (e.g., implementing 'Likes' in a chat). | -| Server-side batching enabled | Batches inbound messages on the server side before sending them to subscribers based on the configured policy. | -| Cancel | Discards changes and closes the dialog without saving the new rule.| - -### Protocol adapter settings - -The following explains the configuration support for various communication protocols ([Pusher](/docs/protocols/pusher), [PubNub](/docs/protocols/pubnub), [MQTT](/docs/protocols/mqtt)), enabling different client libraries to interact with Ably. - -| Settings | Description | -| --------- | ----------- | -| Pusher protocol support | Provides compatibility with the Pusher protocol. | -| PubNub protocol support | Provides compatibility with the PubNub protocol. | -| MQTT protocol support | Provides compatibility with the MQTT protocol. | - -### Actions - -**Delete this app now** to permanently delete your app including your message history, statistics and prevent access to Ably with any of the API keys assigned to this app. diff --git a/src/pages/docs/platform/account/app/stats.mdx b/src/pages/docs/platform/account/app/stats.mdx index 9387307bd7..9575ee976f 100644 --- a/src/pages/docs/platform/account/app/stats.mdx +++ b/src/pages/docs/platform/account/app/stats.mdx @@ -44,5 +44,5 @@ The Stats page also includes a chart that visualizes your app's data over time: The following explains how to use the statistics chart: -* **Duration**: Define a specific time range for the statistics you want to view. This enables you to focus on periods of particular interest. For example, set the time range from "2024-06-17 00:00" to "2024-08-06 11:18" to analyze data within that period. -* **Zoom**: Use preset zoom options (1h, 8h, 24h, 7d, 1m, 6m, 1y, all) to adjust the chart's view to different periods, enabling you to analyze data at various granularities. +* Duration: Define a specific time range for the statistics you want to view. This enables you to focus on periods of particular interest. For example, set the time range from "2024-06-17 00:00" to "2024-08-06 11:18" to analyze data within that period. +* Zoom: Use preset zoom options (1h, 8h, 24h, 7d, 1m, 6m, 1y, all) to adjust the chart's view to different periods, enabling you to analyze data at various granularities. diff --git a/src/pages/docs/platform/account/control-api.mdx b/src/pages/docs/platform/account/control-api.mdx index 6d6d35575d..1556a38f61 100644 --- a/src/pages/docs/platform/account/control-api.mdx +++ b/src/pages/docs/platform/account/control-api.mdx @@ -46,27 +46,27 @@ Using the code-generation capabilities of tools such as [Postman](https://www.po Before you can use the Control API you must create an access token to authenticate with. You can do this in the Ably dashboard. -In the [Ably dashboard](https://ably.com/accounts/any), on the top menu bar, select your account from the dropdown list and then select **My Access Tokens** from the menu: +In the [Ably dashboard](https://ably.com/accounts/any), on the top menu bar, select your account from the dropdown list and then select My Access Tokens from the menu: ![My Settings](../../../../images/content/screenshots/control-api/my-access-tokens-menu-item.png) -You are presented with the **My Access Tokens** area, where you can create tokens for use with the Control API: +You are presented with the My Access Tokens area, where you can create tokens for use with the Control API: ![My Settings](../../../../images/content/screenshots/control-api/my-access-tokens.png) ### Creating an access token -To create a new token, click the **Create new access token** button. Then enter the required information into the dialog: +To create a new token, click the Create new access token button. Then enter the required information into the dialog: 1. Enter a memorable name for your token. 2. Select the capabilities you wish the token to have, depending on your use case. -3. Click the **Create** button to create the token. +3. Click the Create button to create the token. ![My Settings](../../../../images/content/screenshots/control-api/new-access-token.png) ### Using the access token -From the **My access tokens** area you can click the **Copy Token** button, to copy the token to the clipboard. +From the My access tokens area you can click the Copy Token button, to copy the token to the clipboard. You use the access token to authenticate requests to the Control API. To do this, you supply the access token as a Bearer token in the Authorization header of the HTTP request. For example, in the following Curl request replace `` with the token you have copied to the clipboard: @@ -126,7 +126,7 @@ Operations that affect your entire account, such as [listing the apps](/docs/api ### How to find your account ID -In the [Ably dashboard](https://ably.com/accounts/any), on the top menu bar, select your account from the dropdown list and then select **Account settings**: +In the [Ably dashboard](https://ably.com/accounts/any), on the top menu bar, select your account from the dropdown list and then select Account settings: ![Account Settings](../../../../images/content/screenshots/control-api/account-settings-menu-item.png) @@ -138,11 +138,11 @@ You'll need your account ID for account-level Control API requests, such as list ### How to find your app ID -In the [Ably dashboard](https://ably.com/accounts/any) select the app you want to find the app ID for. Click on the **Settings** tab: +In the [Ably dashboard](https://ably.com/accounts/any) select the app you want to find the app ID for. Click on the Settings tab: ![Application Settings](../../../../images/content/screenshots/control-api/application-settings.png) -The **App ID** is displayed under **Application settings**. It is also the first part of your API key for that app. For example, if your API key is `28AB6c.DEFi0Q`, then the App ID is `28AB6c`. You can find out more in the Ably Help Center article [what is an app API key?](/docs/auth#api-key). +The App ID is displayed under Application settings. It is also the first part of your API key for that app. For example, if your API key is `28AB6c.DEFi0Q`, then the App ID is `28AB6c`. You can find out more in the Ably Help Center article [what is an app API key?](/docs/auth#api-key). ## Examples @@ -807,15 +807,15 @@ A convenient way to try out the Control API is by importing the OpenAPI document 1. Make sure you have [Postman](https://www.postman.com/downloads/) installed. -2. Start Postman and select **File > Import** from the main menu. The import dialog is displayed: +2. Start Postman and select File > Import from the main menu. The import dialog is displayed: ![Postman import dialog](../../../../images/content/screenshots/control-api/postman-import-dialog.png) -3. Click the **Link** tab, and paste in the following URL: `https://raw.githubusercontent.com/ably/open-specs/main/definitions/control-v1.yaml`, then click **Continue**: +3. Click the Link tab, and paste in the following URL: `https://raw.githubusercontent.com/ably/open-specs/main/definitions/control-v1.yaml`, then click Continue: ![Link to OpenAPI document](../../../../images/content/screenshots/control-api/postman-link.png) -4. In the Import dialog, use the default settings and click **Import**: +4. In the Import dialog, use the default settings and click Import: ![Postman import default](../../../../images/content/screenshots/control-api/postman-import-default.png) @@ -837,15 +837,15 @@ Now that you have obtained the token and IDs, you can learn how to send a reques ![App list request](../../../../images/content/screenshots/control-api/app-list-request.png) -2. The `Lists account apps` request is an account-level operation and therefore requires your account ID in the `account_id` path variable. This path variable is highlighted with the green box in the previous screenshot. Paste your Ably account ID into the **VALUE** field. +2. The `Lists account apps` request is an account-level operation and therefore requires your account ID in the `account_id` path variable. This path variable is highlighted with the green box in the previous screenshot. Paste your Ably account ID into the VALUE field. -3. You also need to enter your Control API token as a `Bearer Token` in the **Authorization** tab. Paste your Ably Control API token into the token field marked with the placeholder text ``, as shown in the following screenshot: +3. You also need to enter your Control API token as a `Bearer Token` in the Authorization tab. Paste your Ably Control API token into the token field marked with the placeholder text ``, as shown in the following screenshot: ![Bearer token](../../../../images/content/screenshots/control-api/bearer-token.png) -**Note:** If you don't supply this token, your request will fail to authenticate. +Note: If you don't supply this token, your request will fail to authenticate. -4. Now that this request is configured, you can send the request by clicking the **Send** button: +4. Now that this request is configured, you can send the request by clicking the Send button: ![Send request](../../../../images/content/screenshots/control-api/send-request.png) diff --git a/src/pages/docs/platform/account/dashboard-guide.mdx b/src/pages/docs/platform/account/dashboard-guide.mdx new file mode 100644 index 0000000000..1f60b33df4 --- /dev/null +++ b/src/pages/docs/platform/account/dashboard-guide.mdx @@ -0,0 +1,254 @@ +--- +title: Dashboard guide +meta_description: "Complete guide to using the Ably dashboard - create apps, manage account settings, monitor statistics, and configure your realtime applications step by step." +meta_keywords: "Ably dashboard, app management, account settings, statistics monitoring, dashboard tutorial" +--- + +Complete guide to using the Ably dashboard - create apps, manage account settings, monitor statistics, and configure your realtime applications step by step. + +The Ably dashboard is your central hub for managing realtime applications. This guide walks you through every feature with step-by-step instructions. + +## Getting started with the dashboard + +### Accessing your dashboard + +1. Go to [ably.com](https://ably.com) and click Log in +2. Enter your email and password +3. You'll be taken to your dashboard home page + +### Dashboard navigation overview + +The dashboard has a consistent navigation structure: + +- Ably logo - Returns you to the main dashboard +- Top navigation - Three dropdown menus: Developers, Support, Account +- Account dropdown - Access all account-level settings and features + +## Account management + +### Using the account dropdown + +To access account-wide settings: + +1. Click Account in the top navigation bar +2. The dropdown reveals these options: + +| Option | Purpose | +| ------ | ------- | +| Your account | Account overview and general information | +| Settings | Manage account settings and preferences | +| Billing | View billing information and manage subscriptions | +| Limits | Check current account limits and usage thresholds | +| Usage | View account-wide usage statistics | +| Users | Manage team members and permissions | +| My Settings | Personal account settings | +| My Access Tokens | Manage Control API access tokens | +| Log out | Sign out of your account | + +### Managing account settings + +To update your account settings: + +1. Click Account → Settings +2. Update your account information as needed +3. Save your changes + +### Viewing usage and limits + +To monitor your account usage: + +1. Click Account → Usage to see usage across all apps +2. Click Account → Limits to check your current limits +3. Review the data to understand your consumption patterns + +## Creating and managing applications + +### Creating your first app + +When you don't have any apps yet: + +1. You'll see the "Create your first app" welcome screen +2. Read the description: "Create your first app to start building with Ably. An app allows you to build, debug and monitor your realtime software" +3. Click Create new app to start +4. Alternatively, click Invite a developer to add team members + +### Viewing your apps + +Once you have applications: + +1. Your dashboard shows the "Your apps" page +2. Each app is displayed as a card showing: + - App name (e.g., "Demo app - Basketball") + - Last 24h activity summary + - Message count (e.g., "10 Messages") + - Small activity chart + - Peak connections (e.g., "1 Peak Connection") + - View App link + +### Creating additional apps + +To create more applications: + +1. From the "Your apps" page, click + Create new app in the top right +2. Follow the app creation process +3. Your new app will appear on the dashboard + +### Accessing an app + +To open and manage a specific app: + +1. Find the app card on your dashboard +2. Click View App on the desired app card +3. You'll be taken to that app's dashboard + +## Working within an application + +### App-level navigation + +When you're inside an app, you'll see: + +- Breadcrumb navigation showing: Ably Realtime > [App Name] +- Tab navigation with 8 sections: + +| Tab | Purpose | +| --- | ------- | +| Stats | View usage statistics and charts | +| Getting started | Quick start guide and setup | +| API Keys | Create and manage API keys | +| Integrations | Configure webhooks and external services | +| Queues | Set up and manage message queues | +| Notifications | Configure push notifications | +| Dev console | Development and debugging tools | +| Settings | App configuration and rules | + +### Monitoring app statistics + +#### Using the Stats tab + +1. Click the Stats tab (it's selected by default) +2. Choose between two views: + - Chart view - Visual graphs of metrics + - Table view - Detailed numerical data + +#### Understanding the statistics table + +The table shows comprehensive metrics: + +| Metric | Description | +| ------ | ----------- | +| Messages (billable) | Total billable messages across time periods | +| Messages published (REST & Realtime) | Messages sent via REST API and realtime connections | +| Messages received (Realtime) | Messages received by subscribers | +| Messages retrieved (History) | Historical messages fetched | +| Messages persisted (History) | Messages stored for history | +| Presence events (REST & Realtime) | Presence enter/leave/update events | +| Webhook / Function | Messages processed by webhooks | +| Ably Queue | Messages processed through queues | +| Firehose | Messages sent via firehose | +| Push Notifications | Push notification deliveries | +| Data transferred | Bandwidth usage in bytes | +| Peak connections | Maximum concurrent connections | +| Peak channels | Maximum channels used simultaneously | + +#### Reading the time periods + +Statistics are broken down by: + +- Last month - Previous calendar month +- This month (actual) - Current month so far +- This month (forecast) - Projected usage for current month +- Last hour - Previous 60 minutes +- Last minute - Previous 60 seconds + +#### Using the charts view + +1. Above the table, you'll see chart visualization controls +2. Select time ranges using the zoom options: 1h, 8h, 24h, 7d, or All +3. Charts show multiple colored lines for different metrics +4. Use the date range display to see exactly what period you're viewing + +#### Downloading statistics + +To export your data: + +1. Scroll to the bottom of the statistics table +2. Click Download or view detailed app statistics +3. Choose your preferred export format + +### Configuring API keys + +To manage API keys for your app: + +1. Click the API Keys tab +2. Here you can: + - View existing API keys + - Create new keys with specific capabilities + - Delete or modify existing keys + - Set permissions for each key + +### Setting up integrations + +To connect external services: + +1. Click the Integrations tab +2. Configure webhooks to send events to external URLs +3. Set up streaming integrations for real-time data flow +4. Connect with third-party services + +### Managing queues + +To work with message queues: + +1. Click the Queues tab +2. View existing queues and their status +3. Create new queues for message processing +4. Configure queue settings and parameters + +### Configuring notifications + +For push notifications: + +1. Click the Notifications tab +2. Set up push notification credentials +3. Test notification delivery +4. Configure notification rules and targeting + +### Using the dev console + +For development and debugging: + +1. Click the Dev console tab +2. Monitor real-time events +3. Test message publishing and subscribing +4. Debug connection issues + +### Managing app settings + +To configure your app: + +1. Click the Settings tab +2. Update app-level configuration +3. Set channel rules and permissions +4. Configure protocol support + +## Best practices + +### Dashboard organization + +- Create separate apps for development, staging, and production +- Use descriptive names for your apps to easily identify them +- Regular monitoring check your stats regularly to understand usage patterns + +### Account management + +- Monitor usage regularly check your limits and usage to avoid service disruption +- Team management use the Users section to properly manage team access +- Security regularly review and rotate API keys + +### App configuration + +- Start small begin with basic configuration and expand as needed +- Test thoroughly use the dev console to test before deploying +- Documentation keep track of your integration and configuration choices + +This dashboard guide covers all the core functionality you'll need to effectively manage your Ably applications. Each section provides the specific steps to accomplish common tasks, helping you make the most of Ably's realtime infrastructure. \ No newline at end of file diff --git a/src/pages/docs/platform/account/dashboard.mdx b/src/pages/docs/platform/account/dashboard.mdx new file mode 100644 index 0000000000..dd34b6f1c1 --- /dev/null +++ b/src/pages/docs/platform/account/dashboard.mdx @@ -0,0 +1,136 @@ +--- +title: Dashboard overview +meta_description: "Navigate the Ably dashboard to manage your realtime applications, monitor usage statistics, and configure account settings." +meta_keywords: "Ably dashboard, app management, usage monitoring, account settings, realtime applications" +redirect_from: + - /docs/account/dashboard +--- + +Navigate the Ably dashboard to manage your realtime applications, monitor usage statistics, and configure account settings. + +The Ably dashboard provides an intuitive interface for managing all aspects of your realtime infrastructure. Access your dashboard by [logging in](https://ably.com/login) to your Ably account. + +## Dashboard structure + +### Main navigation + +The dashboard features a clean navigation structure: + +- Ably Realtime logo - Returns you to your apps overview +- Top navigation bar with three dropdown menus: + - Developers - Documentation and developer resources + - Support - Help and support options + - Account - Account management and settings + +### Account dropdown menu + +The Account dropdown provides access to all account-level features: + +| Section | Description | +| ------- | ----------- | +| [Your account](/docs/platform/account/your-account) | Account overview and general information | +| [Settings](/docs/platform/account/account-settings) | Account settings and configuration | +| [Billing](/docs/platform/pricing/billing) | Billing information and subscription management | +| [Limits](/docs/platform/account/limits) | Current account limits and usage thresholds | +| [Usage](/docs/platform/account/usage) | Account-wide usage statistics across all applications | +| [Users](/docs/platform/account/users) | Team member management and permissions | +| [My Settings](/docs/platform/account/my-settings) | Personal account settings and preferences | +| [My Access Tokens](/docs/platform/account/my-access-tokens) | Control API access token management | +| Log out | Sign out of your account | + +## Application management + +### Apps overview + +Your main dashboard displays all your applications: + +- "Your apps" page showing all applications as cards +- "Create new app" button for creating new applications +- App cards displaying key metrics for each application + +### App information cards + +Each app card shows: + +- Application name +- Last 24 hours activity summary +- Recent message count +- Simple activity chart visualization +- Peak connection count +- "View App" link to access the app dashboard + +### First-time experience + +New users see a welcome interface with: + +- "Create your first app" call-to-action +- Description of what an app enables +- "Create new app" and "Invite a developer" buttons +- Examples section with inspiring use cases + +## App-level management + +When you access a specific application, you get a dedicated app dashboard with 7 main sections: + +| Tab | Purpose | +| --- | ------- | +| [Stats](/docs/platform/account/app/stats) | Usage statistics, charts, and performance metrics | +| [API Keys](/docs/platform/account/app/api) | API key creation and management | +| [Integrations](/docs/platform/account/app/integrations) | Webhook and external service configuration | +| [Queues](/docs/platform/account/app/app-queues) | Message queue setup and monitoring | +| [Notifications](/docs/platform/account/app/app-notifications) | Push notification configuration | +| [Dev console](/docs/platform/account/app/dev-console) | Real-time development and debugging tools | +| [CLI testing](/docs/platform/account/app/cli-testing) | Command-line testing and automation tools | +| [Settings](/docs/platform/account/app/app-settings) | Application configuration and channel rules | + +### Statistics monitoring + +The Stats tab provides comprehensive monitoring: + +- Detailed statistics table with metrics broken down by time periods +- Interactive charts showing visual representations of your data +- Multiple time ranges from minutes to months +- Export capabilities for detailed analysis +- Forecast projections for usage planning + +## Getting started + +### Quick start workflow + +1. Log in to your Ably account +2. Create your first app using the dashboard interface +3. Generate API keys in the API Keys tab +4. Configure integrations if needed +5. Monitor usage through the Stats tab + +### Common tasks + +Use the dashboard to: + +- Monitor application performance through real-time statistics +- Manage API keys with specific capabilities and permissions +- Configure webhooks for external integrations +- Debug applications using the dev console +- Track usage against your account limits +- Manage team access through user management + +## Interface design + +The dashboard follows modern design principles: + +- Card-based layouts for easy information scanning +- Tabbed navigation for logical feature organization +- Interactive charts with zoom and time controls +- Responsive design that works across devices +- Clear breadcrumbs showing your current location + +## Complete dashboard guide + +For detailed step-by-step instructions on using every feature of the dashboard, see the [complete dashboard guide](/docs/platform/account/dashboard-guide) which covers: + +- Detailed walkthrough of every dashboard section +- Step-by-step instructions for common tasks +- Best practices for dashboard organization +- Tips for effective app and account management + +The dashboard provides everything you need to effectively manage your Ably realtime applications, from initial setup through production monitoring and scaling. \ No newline at end of file diff --git a/src/pages/docs/platform/account/enterprise-customization.mdx b/src/pages/docs/platform/account/enterprise-customization.mdx index 92197df19d..26811b46a3 100644 --- a/src/pages/docs/platform/account/enterprise-customization.mdx +++ b/src/pages/docs/platform/account/enterprise-customization.mdx @@ -7,12 +7,12 @@ redirect_from: - /docs/root/platform-customization --- -If you're an [Ably Enterprise](https://ably.com/pricing) customer, then you can optionally create a **custom endpoint** to tailor the Ably platform to your specific requirements. A custom endpoint enables you to benefit from the following: +If you're an [Ably Enterprise](https://ably.com/pricing) customer, then you can optionally create a custom endpoint to tailor the Ably platform to your specific requirements. A custom endpoint enables you to benefit from the following: -* **Active traffic management**: Let Ably actively monitor not only the global cluster health but also your own domains and proactively take steps to isolate or move traffic to ensure business continuity. -* **Dedicated, isolated clusters**: Rely upon guaranteed capacity and isolation from noisy neighbors. -* **Regional routing of traffic**: Require that all traffic is routed and serviced within specific regions. -* **Regional message storage**: Require that all messages are stored within a specific region. +* Active traffic management: Let Ably actively monitor not only the global cluster health but also your own domains and proactively take steps to isolate or move traffic to ensure business continuity. +* Dedicated, isolated clusters: Rely upon guaranteed capacity and isolation from noisy neighbors. +* Regional routing of traffic: Require that all traffic is routed and serviced within specific regions. +* Regional message storage: Require that all messages are stored within a specific region. A custom endpoint provides you with an option to service Ably platform requests. These can be either subdomains of `ably.net`, or point at your own custom CNAME domain. If you choose the latter option, Ably can also customize our client library SDKs to use your chosen domain and make them available via our CDN as `cdn.ably.com/lib/yourcompany.min.js`. @@ -113,9 +113,9 @@ Test your custom endpoint by visiting it. The URL for your endpoint will depend For example, if you have elected to use an Ably subdomain, you should test your endpoint by replacing `[ENDPOINT]` with the value of the `endpoint` property in the `ClientOptions` object: -* **Primary domain**: `https://[ENDPOINT].realtime.ably.net/time`, for example: `https://endpoint-example.realtime.ably.net/time`. +* Primary domain: `https://[ENDPOINT].realtime.ably.net/time`, for example: `https://endpoint-example.realtime.ably.net/time`. -* **Fallback domains**: `https://[ENDPOINT].[a-e].fallback.ably-realtime.com/time`, for example: `https://endpoint-example.a.fallback.ably-realtime.com/time`. +* Fallback domains: `https://[ENDPOINT].[a-e].fallback.ably-realtime.com/time`, for example: `https://endpoint-example.a.fallback.ably-realtime.com/time`. Repeat this step for all fallback hosts in the `fallbackHosts` array, if provided. @@ -160,5 +160,5 @@ Once all your client library SDKs are using the new endpoint and traffic is arri If you have regional constraints on your account, then please contact your customer success manager who will ensure that the regional constraints are applied and tested too. diff --git a/src/pages/docs/platform/account/index.mdx b/src/pages/docs/platform/account/index.mdx index 98b7715222..80ec928ee6 100644 --- a/src/pages/docs/platform/account/index.mdx +++ b/src/pages/docs/platform/account/index.mdx @@ -8,10 +8,25 @@ redirect_from: Manage all aspects of your account, from Two-factor authentication ([2FA](/docs/platform/account/2fa)) and billing to user management and personal preferences. -Begin by [logging](https://ably.com/login) in to Ably through your browser. Once you're logged in, you have access to the Ably dashboard, where you can click on the Account navigation dropdown to access the account settings: +Begin by [logging](https://ably.com/login) in to Ably through your browser. Once you're logged in, you have access to the Ably [dashboard](/docs/platform/account/dashboard), where you can click on the Account navigation dropdown to access the account settings: ![Ably Account Settings](../../../../images/content/screenshots/dash/account.png) +## Dashboard navigation + +The Ably [dashboard](/docs/platform/account/dashboard) provides access to account management through the account dropdown menu, which includes the following sections: + +### Account management sections + +| Section | Description | +| ------- | ----------- | +| [Your account](/docs/platform/account/your-account) | Account overview and general information | +| [Account settings](/docs/platform/account/account-settings) | Account configuration and preferences | +| [Limits](/docs/platform/account/limits) | Current account limits and usage thresholds | +| [Usage](/docs/platform/account/usage) | Account-wide usage statistics across all applications | +| [My Settings](/docs/platform/account/my-settings) | Personal account settings and preferences | +| [My Access Tokens](/docs/platform/account/my-access-tokens) | Control API access token management | + ### Settings Manage your Ably account settings, including authentication, [billing](/docs/platform/pricing/billing), and account ownership: diff --git a/src/pages/docs/platform/account/limits.mdx b/src/pages/docs/platform/account/limits.mdx new file mode 100644 index 0000000000..a0ecb5b4a0 --- /dev/null +++ b/src/pages/docs/platform/account/limits.mdx @@ -0,0 +1,179 @@ +--- +title: Limits +meta_description: "Monitor your Ably account limits, usage thresholds, and quota restrictions to ensure optimal service performance." +meta_keywords: "Ably account limits, usage quotas, service limits, account thresholds, usage monitoring" +redirect_from: + - /docs/account/limits +--- + +Monitor your Ably account limits, usage thresholds, and quota restrictions to ensure optimal service performance. + +Account limits help protect your applications from unexpected usage spikes and ensure fair resource allocation across the Ably platform. + +## Accessing account limits + +To view your current limits: + +1. Click Account in the top navigation bar +2. Select Limits from the dropdown menu +3. View your account limits dashboard + +## Types of account limits + +### Connection limits + +Monitor concurrent connection restrictions: + +| Limit Type | Description | +| ---------- | ----------- | +| Peak concurrent connections | Maximum simultaneous connections allowed | +| Connection rate limits | Maximum new connections per time period | +| Connection duration limits | Maximum duration for individual connections | + +### Message limits + +Track message-related quotas: + +| Limit Type | Description | +| ---------- | ----------- | +| Message rate limits | Maximum messages per second/minute/hour | +| Message size limits | Maximum size per individual message | +| Daily/monthly message quotas | Total message allowances per time period | + +### Channel limits + +Understand channel restrictions: + +| Limit Type | Description | +| ---------- | ----------- | +| Peak concurrent channels | Maximum simultaneous channels | +| Channel creation rate | Maximum new channels per time period | +| Channel name length limits | Character restrictions for channel names | + +### Data transfer limits + +Monitor bandwidth restrictions: + +| Limit Type | Description | +| ---------- | ----------- | +| Bandwidth quotas | Data transfer allowances per time period | +| Payload size limits | Maximum data per message or event | +| History retention limits | Storage duration for message history | + +## Understanding limit status + +### Current usage display + +The limits page shows: + +- Current usage as a percentage of your limit +- Absolute numbers for both usage and limits +- Time period for rate-based limits +- Status indicators (green, yellow, red) for different usage levels + +### Limit types explained + +| Status | Description | Action Required | +| ------ | ----------- | --------------- | +| Green | Usage well below limits | No action needed | +| Yellow | Usage approaching limits | Monitor closely | +| Red | Usage at or near limits | Consider upgrading or optimizing | + +### Limit reset periods + +Different limits reset on different schedules: + +- Per-second limits reset continuously +- Per-minute limits reset every 60 seconds +- Daily limits reset at midnight UTC +- Monthly limits reset on your billing cycle date + +## Managing account limits + +### Monitoring usage patterns + +To stay within limits: + +1. Check the limits page regularly +2. Set up alerts for approaching thresholds +3. Monitor usage trends over time +4. Identify peak usage periods + +### Optimizing usage + +When approaching limits: + +1. Review application efficiency - Optimize message frequency and size +2. Implement batching - Group multiple small messages together +3. Use appropriate channels - Avoid unnecessary channel proliferation +4. Optimize connection patterns - Minimize connection churn + +### Requesting limit increases + +If you need higher limits: + +1. Contact [Ably support](mailto:support@ably.com) with your requirements +2. Provide details about your use case and expected growth +3. Specify which limits need adjustment +4. Consider upgrading to a higher-tier plan + +## Limit-related best practices + +### Proactive monitoring + +- Check limits regularly, especially during development +- Set up monitoring alerts before reaching 80% of limits +- Understand which limits apply to your specific use case +- Plan for growth by monitoring usage trends + +### Application design + +- Design applications to handle rate limiting gracefully +- Implement exponential backoff for retries +- Use appropriate message sizes and frequencies +- Consider limit implications during architecture planning + +### Development and testing + +- Use separate development/staging apps to avoid impacting production limits +- Test applications under load to understand limit requirements +- Design applications to degrade gracefully when limits are reached +- Implement client-side rate limiting where appropriate + +### Emergency procedures + +- Have a plan for when limits are reached unexpectedly +- Know how to quickly contact support for emergency limit increases +- Implement application-level safeguards against runaway usage +- Monitor for unusual usage spikes that might indicate issues + +## Common limit scenarios + +### Approaching connection limits + +When nearing connection limits: + +1. Review connection lifecycle management +2. Implement connection pooling where possible +3. Optimize connection reuse patterns +4. Consider upgrading your plan + +### Message rate limit issues + +When hitting message rate limits: + +1. Implement message batching strategies +2. Review message frequency requirements +3. Consider using presence events for state rather than messages +4. Optimize message payload sizes + +### Channel proliferation + +When approaching channel limits: + +1. Review channel naming and organization strategies +2. Implement channel cleanup for unused channels +3. Consider using channel namespaces more effectively +4. Optimize channel lifecycle management + +Account limits are designed to ensure reliable service delivery. Understanding and monitoring these limits helps you build robust, scalable applications on the Ably platform. \ No newline at end of file diff --git a/src/pages/docs/platform/account/my-access-tokens.mdx b/src/pages/docs/platform/account/my-access-tokens.mdx new file mode 100644 index 0000000000..d771901c4f --- /dev/null +++ b/src/pages/docs/platform/account/my-access-tokens.mdx @@ -0,0 +1,239 @@ +--- +title: My Access Tokens +meta_description: "Create and manage personal access tokens for the Ably Control API to programmatically interact with your account and applications." +meta_keywords: "Ably access tokens, Control API tokens, API authentication, personal tokens, programmatic access" +redirect_from: + - /docs/account/my-access-tokens +--- + +Create and manage personal access tokens for the Ably Control API to programmatically interact with your account and applications. + +Access tokens provide secure, programmatic access to Ably's Control API, allowing you to automate account and application management tasks. + +## Accessing token management + +To manage your access tokens: + +1. Click Account in the top navigation bar +2. Select My Access Tokens from the dropdown menu +3. View and manage your personal access tokens + +## Understanding access tokens + +### What are access tokens + +Access tokens are secure credentials that allow: + +- Programmatic access to the Ably Control API +- Automation of account and application management +- Integration with CI/CD pipelines and scripts +- Administrative tasks without manual dashboard interaction + +### Token capabilities + +Access tokens can be configured with specific permissions: + +| Capability | Description | +| ---------- | ----------- | +| Read account information | View account details and settings | +| Manage applications | Create, update, and delete applications | +| Configure API keys | Manage application API keys | +| Access statistics | Retrieve usage and performance data | +| Manage integrations | Configure webhooks and external services | +| User management | Add, remove, and modify user permissions | + +### Token security + +Important security characteristics: + +- Tokens are displayed only once during creation +- Each token has specific, limited capabilities +- Tokens can be revoked immediately if compromised +- Token usage is logged for security auditing + +## Creating access tokens + +### Token creation process + +To create a new access token: + +1. Click Create new token on the access tokens page +2. Provide a descriptive name for the token +3. Select the account (if you have access to multiple accounts) +4. Choose specific capabilities for the token +5. Click Create token +6. Important: Copy and securely store the token immediately + +### Token configuration options + +When creating tokens, configure: + +| Setting | Description | +| ------- | ----------- | +| Token name | Descriptive name for identification purposes | +| Account scope | Which account the token can access | +| Capabilities | Specific permissions granted to the token | +| Expiration | Optional expiration date for the token | + +### Capability selection + +Choose appropriate capabilities based on intended use: + +- Minimal permissions - Grant only the capabilities needed +- Specific scope - Limit access to relevant resources +- Time-limited - Consider expiration dates for temporary use +- Purpose-specific - Create different tokens for different use cases + +## Managing existing tokens + +### Viewing token information + +For each token, you can see: + +| Information | Description | +| ----------- | ----------- | +| Token name | Descriptive name you provided | +| Created date | When the token was created | +| Last used | Most recent token usage (if any) | +| Capabilities | Permissions granted to the token | +| Status | Active or revoked status | + +### Token operations + +Available actions for existing tokens: + +| Action | Description | +| ------ | ----------- | +| View details | See token capabilities and usage history | +| Regenerate | Create a new token with same permissions | +| Revoke | Immediately disable the token | +| Update name | Modify the descriptive name | + +### Revoking tokens + +To revoke an access token: + +1. Find the token in your access tokens list +2. Click Revoke next to the token +3. Confirm the revocation +4. Note: This action is immediate and irreversible + +## Using access tokens + +### API authentication + +Use tokens to authenticate with the Control API: + + +```bash +curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ + https://control.ably.net/v1/accounts +``` + + +### Common use cases + +Access tokens are typically used for: + +| Use Case | Description | +| -------- | ----------- | +| CI/CD automation | Deploy and configure applications automatically | +| Infrastructure as code | Manage Ably resources through scripts | +| Monitoring integration | Fetch statistics for external monitoring | +| Bulk operations | Perform administrative tasks at scale | + +### Integration examples + +Example integrations using access tokens: + +- Terraform - Manage Ably resources as infrastructure +- GitHub Actions - Automate deployment workflows +- Monitoring scripts - Collect usage data for analysis +- Administrative tools - Build custom management interfaces + +## Access token security + +### Storage best practices + +Securely store access tokens: + +- Never commit tokens to version control +- Use environment variables or secure secret stores +- Rotate tokens regularly for enhanced security +- Document token usage for team awareness + +### Monitoring token usage + +Track token security: + +- Review token usage logs regularly +- Monitor for unexpected token activity +- Set up alerts for token usage anomalies +- Audit token permissions periodically + +### Security incident response + +If a token is compromised: + +1. Immediately revoke the compromised token +2. Review logs to understand potential impact +3. Create new token if continued access is needed +4. Update systems with the new token +5. Document incident for future prevention + +## Token management best practices + +### Token lifecycle management + +- Regular auditing - Review tokens quarterly +- Purpose documentation - Maintain clear records of token purposes +- Expiration planning - Set expiration dates where appropriate +- Team coordination - Ensure team members know about shared tokens + +### Capability management + +- Principle of least privilege - Grant minimal necessary permissions +- Purpose-specific tokens - Create separate tokens for different use cases +- Regular review - Ensure capabilities remain appropriate +- Documentation - Keep records of why capabilities were granted + +### Integration maintenance + +- Dependency tracking - Know which systems use which tokens +- Update procedures - Have processes for rotating tokens +- Backup plans - Prepare for token revocation scenarios +- Testing - Verify token functionality after changes + +## Common token management tasks + +### Rotating expired tokens + +When tokens expire or need rotation: + +1. Create a new token with the same capabilities +2. Update all systems using the old token +3. Test that new token works correctly +4. Revoke the old token +5. Document the rotation for team records + +### Troubleshooting token issues + +Common token problems and solutions: + +| Issue | Solution | +| ----- | -------- | +| Authentication failures | Verify token is correct and not revoked | +| Permission errors | Check token capabilities match required operations | +| Rate limiting | Ensure token usage stays within API limits | +| Expired tokens | Create new tokens and update integrations | + +### Token inventory management + +Maintain an inventory of tokens: + +- Document what each token is used for +- Track which systems and team members use each token +- Plan token rotation schedules +- Maintain emergency contact information for token owners + +Access tokens provide powerful automation capabilities while requiring careful security management to protect your Ably account and applications. \ No newline at end of file diff --git a/src/pages/docs/platform/account/my-settings.mdx b/src/pages/docs/platform/account/my-settings.mdx new file mode 100644 index 0000000000..310f0a0dd8 --- /dev/null +++ b/src/pages/docs/platform/account/my-settings.mdx @@ -0,0 +1,237 @@ +--- +title: My Settings +meta_description: "Manage your personal Ably account settings, preferences, and individual user configuration through the dashboard." +meta_keywords: "Ably personal settings, user preferences, individual settings, profile management, personal configuration" +redirect_from: + - /docs/account/my-settings +--- + +Manage your personal Ably account settings, preferences, and individual user configuration through the dashboard. + +"My Settings" allows you to customize your individual experience with the Ably dashboard and configure personal preferences that don't affect other team members. + +## Accessing personal settings + +To manage your individual settings: + +1. Click Account in the top navigation bar +2. Select My Settings from the dropdown menu +3. Configure your personal preferences + +## Personal profile settings + +### Basic profile information + +Manage your personal details: + +| Setting | Description | +| ------- | ----------- | +| Display name | Your name as shown in the dashboard | +| Email address | Your login email and contact address | +| Profile picture | Optional avatar for team identification | +| Time zone | Personal time zone for timestamps | + +### Contact preferences + +Configure how you receive communications: + +| Preference | Options | +| ---------- | ------- | +| Email notifications | Enable/disable various notification types | +| Product updates | Stay informed about new Ably features | +| Security alerts | Important account security notifications | +| Marketing communications | Optional promotional emails | + +### Dashboard preferences + +Customize your dashboard experience: + +| Setting | Description | +| ------- | ----------- | +| Default landing page | Which page loads when you log in | +| Dashboard theme | Light/dark mode preferences | +| Data refresh frequency | How often dashboard data updates | +| Default time ranges | Preferred time periods for charts | + +## Security settings + +### Authentication management + +Control your account access: + +| Setting | Description | +| ------- | ----------- | +| Password | Update your account password | +| Two-factor authentication | Enable/configure 2FA for your account | +| Login notifications | Get alerts for account access | +| Active sessions | View and manage current login sessions | + +### Connected accounts + +Manage external account connections: + +| Connection Type | Purpose | +| --------------- | ------- | +| GitHub integration | Link GitHub account for enhanced features | +| Google authentication | Enable Google login for your account | +| SSO connections | Enterprise single sign-on integration | + +### API access + +Manage personal API access: + +- View API keys assigned to you +- Access personal development tokens +- Manage webhook authentication +- Configure integration permissions + +## Notification preferences + +### Email notifications + +Configure which emails you receive: + +| Notification Type | Description | +| ----------------- | ----------- | +| Account alerts | Critical account issues and updates | +| Usage notifications | Alerts when approaching limits | +| Security alerts | Login attempts and security events | +| Product announcements | New features and platform updates | + +### Dashboard notifications + +Control in-dashboard alerts: + +| Setting | Description | +| ------- | ----------- | +| Real-time alerts | Live notifications in the dashboard | +| Alert frequency | How often to show non-critical alerts | +| Alert persistence | How long alerts remain visible | +| Sound notifications | Audio alerts for critical events | + +### Mobile notifications + +If using mobile apps: + +- Push notification preferences +- Mobile alert schedules +- Emergency notification overrides +- Mobile-specific alert types + +## Privacy and data settings + +### Data privacy preferences + +Control your data usage: + +| Setting | Description | +| ------- | ----------- | +| Analytics tracking | Allow Ably to track your usage patterns | +| Product improvement | Share data to help improve Ably services | +| Personalization | Use your data to customize your experience | +| Third-party sharing | Control data sharing with partners | + +### Data export and deletion + +Manage your personal data: + +- Export your personal data and settings +- Request deletion of personal information +- Download usage history and activity logs +- Manage data retention preferences + +## Managing personal settings + +### Updating profile information + +To modify your profile: + +1. Navigate to the profile section in My Settings +2. Click Edit next to the information you want to change +3. Update your details +4. Click Save to apply changes +5. Verify changes appear correctly in the dashboard + +### Configuring notifications + +To customize notifications: + +1. Access the notifications section +2. Review each notification type and its purpose +3. Enable or disable notifications based on your preferences +4. Set frequency and timing preferences +5. Test critical notifications to ensure they work + +### Setting up two-factor authentication + +To enhance your account security: + +1. Navigate to the security section +2. Click Enable Two-Factor Authentication +3. Choose your preferred 2FA method (app, SMS, etc.) +4. Follow the setup instructions +5. Test the 2FA setup before relying on it + +## Personal settings best practices + +### Security hygiene + +- Enable two-factor authentication for enhanced security +- Use a strong, unique password for your Ably account +- Regularly review active sessions and revoke unused ones +- Keep your contact information up to date for security alerts + +### Productivity optimization + +- Customize dashboard preferences to match your workflow +- Set up relevant notifications while avoiding notification fatigue +- Configure default time ranges that match your typical analysis needs +- Use appropriate landing pages for your most common tasks + +### Privacy awareness + +- Review privacy settings periodically +- Understand what data is collected and how it's used +- Configure data sharing preferences according to your comfort level +- Take advantage of data export options for your records + +### Regular maintenance + +- Update profile information when it changes +- Review and clean up notification preferences quarterly +- Check connected accounts and remove unused integrations +- Verify security settings remain appropriate for your needs + +## Common personal setting tasks + +### Changing your email address + +To update your login email: + +1. Verify access to both old and new email addresses +2. Navigate to profile settings +3. Update email address +4. Confirm change via verification emails +5. Test login with new email address + +### Resetting your password + +To change your password: + +1. Access security settings +2. Click Change Password +3. Enter current password and new password +4. Confirm the password change +5. Update password in any saved password managers + +### Managing connected services + +To link or unlink external accounts: + +1. Navigate to connected accounts section +2. Review currently connected services +3. Add new connections or remove unused ones +4. Test integrations after making changes +5. Update any dependent workflows or applications + +Personal settings ensure your Ably dashboard experience is tailored to your individual needs while maintaining security and productivity. \ No newline at end of file diff --git a/src/pages/docs/platform/account/organizations.mdx b/src/pages/docs/platform/account/organizations.mdx index 18691f1446..8cde3f0383 100644 --- a/src/pages/docs/platform/account/organizations.mdx +++ b/src/pages/docs/platform/account/organizations.mdx @@ -10,7 +10,7 @@ Use organizations to manage multiple Ably accounts by centralizing user access a Organizations enable the [primary](#primary) account to assign and adjust the roles of users and groups across all accounts. -You can separate accounts within an organization to create isolated environments, such as production, staging, and development. Assign each environment a [package](/docs/pricing#packages) that meets its specific needs. For example, production may need high capacity with an **Enterprise** package, staging might use a **Standard** package, and development a **Free** package. +You can separate accounts within an organization to create isolated environments, such as production, staging, and development. Assign each environment a [package](/docs/pricing#packages) that meets its specific needs. For example, production may need high capacity with an Enterprise package, staging might use a Standard package, and development a Free package. -Manage access to multiple Ably accounts through a single identity provider. To enable this, configure both [SSO](/docs/platform/account/sso) with your chosen identity provider and [SCIM](#SCIM). Once configured, Ably automatically provisions and deprovisions users with access to the Ably app in your identity provider, either individually or through assigned groups. New users are added to Ably's default provisioning account with the role of **Developer**. +Manage access to multiple Ably accounts through a single identity provider. To enable this, configure both [SSO](/docs/platform/account/sso) with your chosen identity provider and [SCIM](#SCIM). Once configured, Ably automatically provisions and deprovisions users with access to the Ably app in your identity provider, either individually or through assigned groups. New users are added to Ably's default provisioning account with the role of Developer. Ably only recognizes one registered email domain per organization, unrecognized email domains will result in rejected provisioning attempts. @@ -50,33 +50,33 @@ The following steps outline the process for provisioning users through SCIM: * Configure [SSO](/docs/platform/account/sso) by enabling and setting up SSO between Ably and your identity provider. * Copy Ably SCIM configuration values: - * Open the **Account** navigation dropdown in the Ably dashboard. - * Select **Organization Settings** from the menu. - * Navigate to the **Users & Groups Provisioning (SCIM)** section and copy: - * **Service Provider Configuration Endpoint.** - * **SCIM Username.** - * **SCIM Password.** + * Open the Account navigation dropdown in the Ably dashboard. + * Select Organization Settings from the menu. + * Navigate to the Users & Groups Provisioning (SCIM) section and copy: + * Service Provider Configuration Endpoint. + * SCIM Username. + * SCIM Password. * In your identity providers provisioning app, paste the following values from Ably: - * **Service Provider Configuration Endpoint.** - * **SCIM Username.** - * **SCIM Password.** + * Service Provider Configuration Endpoint. + * SCIM Username. + * SCIM Password. * Ensure that any additional setup required by your identity provider is completed to finalize the SCIM configuration. ## Manage roles -Manage user and group [roles](/docs/platform/account/users#roles) across accounts within your organization. User and group roles include those assigned directly to the user and through the groups the user belongs to. Use the **Organization Users** page as a central point of control, rather than managing access individually within each account. +Manage user and group [roles](/docs/platform/account/users#roles) across accounts within your organization. User and group roles include those assigned directly to the user and through the groups the user belongs to. Use the Organization Users page as a central point of control, rather than managing access individually within each account. ### Group roles When organizations and your identity provider are configured, the groups you create in the identity provider are synchronized with Ably. This allows you to manage group-based access centrally. Assign roles to these groups and all users in a group will inherit those roles. To manage group roles in Ably: -* Open the **Account** navigation dropdown. - * Click **Organization Users**. - * Under **Ably Realtime identity provider groups**, click **Manage account access**. +* Open the Account navigation dropdown. + * Click Organization Users. + * Under Ably Realtime identity provider groups, click Manage account access. * Select the group whose access you want to manage. - * Specify the required **Roles** for the group -- and all users in this group inherit these roles automatically. + * Specify the required Roles for the group -- and all users in this group inherit these roles automatically.