δΈ­

Integration FAQ

Common questions and answers about integrating with the OpenDev platform.

OAuth Integration

Q: Which OAuth providers are supported?

A: OpenDev supports the following OAuth providers:

  • Google - For global users
  • Facebook - For global users
  • Apple Sign In - For iOS, macOS, and Web
  • WeChat - For Chinese market users
  • QQ - For Chinese market users

Q: What callback URL format should I use?

A: The callback URL format depends on your environment:

Production: https://yourdomain.com/auth/{provider}/callback
Development: http://localhost:3000/auth/{provider}/callback

Replace {provider} with: google, facebook, apple, wechat, or qq.

Q: How do I handle OAuth errors?

A: Common OAuth errors and solutions:

Error Code Description Solution
invalid_client Client ID or Secret is incorrect Verify your OAuth credentials in OpenDev
redirecturimismatch Callback URL doesn't match Ensure the callback URL in provider console matches OpenDev config
access_denied User denied authorization Handle gracefully and show user-friendly message
invalid_scope Requested scope not allowed Check provider documentation for valid scopes

Q: Can I use the same OAuth configuration for multiple environments?

A: It's recommended to use separate OAuth applications for each environment:

  • Development - For local testing
  • Staging - For pre-production testing
  • Production - For live users

This ensures better security and easier debugging.

Q: How do I refresh an expired OAuth token?

A: Token refresh depends on the provider:

  1. Google/Facebook: Use the refresh token to obtain a new access token
  2. Apple: Refresh tokens are long-lived; re-authentication may be needed
  3. WeChat/QQ: Tokens typically have 30-day validity; refresh using the provided refresh token

Payment Integration

Q: What payment methods are supported?

A: OpenDev supports:

  • Stripe - Credit cards, wallets (Web, Desktop)
  • Google Play Billing - Android in-app purchases
  • Apple In-App Purchase - iOS/macOS purchases
  • WeChat Pay - Chinese mobile payments

Q: How do I test payments in development?

A: Each payment provider offers sandbox/test modes:

Provider Test Mode Setup
Stripe Use test API keys (start with sktest)
Google Play Add test accounts in Google Play Console
Apple IAP Use Sandbox environment in App Store Connect
WeChat Pay Apply for sandbox merchant account

Q: How do I handle payment webhooks?

A: Webhook handling best practices:

  1. Verify signatures - Always validate webhook signatures
  2. Idempotency - Handle duplicate webhooks gracefully
  3. Quick response - Return 200 status within 5 seconds
  4. Async processing - Queue heavy processing for background jobs
  5. Logging - Log all webhook events for debugging

Q: What happens if a payment fails?

A: Payment failure handling:

  1. Client-side: Show appropriate error message to user
  2. Retry logic: Implement exponential backoff for retries
  3. Webhook: Listen for payment_failed events
  4. User notification: Send email/push notification about failed payment

Q: How do I handle refunds?

A: Refund process varies by provider:

  • Stripe: Use Stripe Dashboard or API to initiate refunds
  • Google Play: Process through Google Play Console
  • Apple IAP: Handle through App Store Connect
  • WeChat Pay: Use merchant portal or API

SDK Integration

Q: Which platforms are supported?

A: OpenDev SDKs are available for:

  • iOS (Swift/Objective-C)
  • Android (Kotlin/Java)
  • Desktop - Windows & macOS
  • Web (JavaScript/TypeScript)
  • Server (Node.js, Python, Java)

Q: What is the minimum SDK version requirement?

A: Minimum requirements:

  • iOS: iOS 12.0+
  • Android: API Level 21 (Android 5.0)+
  • Desktop: Windows 10+, macOS 10.14+
  • Web: ES6+ browsers

Q: How do I update the SDK?

A: SDK update process:

  1. Check the SDK Downloads page for latest versions
  2. Download the new SDK package
  3. Replace existing SDK files in your project
  4. Update configuration if required (check release notes)
  5. Test thoroughly before deploying

Q: How do I debug SDK issues?

A: Debugging tips:

  1. Enable debug logging: Set debug: true in SDK configuration
  2. Check console logs: Look for error messages and stack traces
  3. Verify configuration: Ensure app ID and credentials are correct
  4. Network inspection: Use Charles/Fiddler to inspect API calls
  5. Contact support: Provide logs and reproduction steps

Configuration

Q: How do I generate a configuration package?

A: Steps to generate configuration:

  1. Go to OpenDev Dashboard > Apps
  2. Select your application
  3. Navigate to Configuration Delivery tab
  4. Choose environment (Development/Production)
  5. Click Generate Configuration
  6. Download and integrate into your app

Q: What is the config.json format?

A: The configuration file contains:

{
  "appId": "your-app-id",
  "channelId": "channel-identifier",
  "environment": "production",
  "oauth": {
    "providers": ["google", "apple"]
  },
  "payment": {
    "providers": ["stripe"]
  }
}

Q: How often should I update the configuration?

A: Configuration update recommendations:

  • Development: Update frequently during development
  • Production: Update when adding new features or providers
  • Hotfixes: Push config updates for urgent fixes

Use CDN delivery for dynamic configuration updates without app releases.

Troubleshooting

Q: API requests are returning 401 Unauthorized

A: Common causes and solutions:

  1. Expired token: Refresh your access token
  2. Invalid credentials: Verify API key/secret
  3. Missing headers: Ensure Authorization: Bearer {token} header is set
  4. Wrong environment: Check you're using correct environment credentials

Q: Webhooks are not being received

A: Webhook troubleshooting:

  1. URL accessibility: Ensure webhook URL is publicly accessible
  2. HTTPS required: Most providers require HTTPS
  3. Firewall rules: Check firewall allows incoming connections
  4. Retry mechanism: Check provider's retry policy and logs

Q: How do I report a bug or request a feature?

A: Contact methods:

  1. Email: contact@zinben.com
  2. Dashboard: Use the feedback form in OpenDev Dashboard
  3. Documentation: Submit corrections through feedback links

Last updated: January 2026