ECall Partner Onboarding Guide¶

Step-by-step guide from account registration to iOS app deployment.

Need more details? See Partner Technical Reference for Xcode setup, troubleshooting, branding, and compliance.

Target Audience¶

• iOS developers integrating ECall open-source for a branded app
• Technical partners with Apple Developer accounts

Prerequisites¶

• You own an Apple Developer Account
• You can build and run iOS apps using Xcode

1. Register Partner Account¶

Action¶

1. Open the registration page:

2. 👉 http://ecall.org/auth/registration

3. Fill in the following fields:

4. Email: Partner email address
5. Password / Confirm Password
6. App Title: Full application name

7. App Short Name: Short, unique identifier (no spaces)

8. Click Register

9. Verify OTP

Expected Result¶

• Partner account is created successfully
• You can log in to the ECall web dashboard

2. Create Apple Certificates (Local CSR → Apple Developer Portal)¶

This step creates the required Apple certificates used for Sign in with Apple, Push Notification and VoIP Push, which are mandatory for incoming calls (CallKit).

2.1 Create Sign in with Apple Key (.p8)¶

This section creates the Apple Authentication Key used for Sign in with Apple.

Action¶

1. Go to Apple Developer Portal

2. 👉 https://developer.apple.com/account

3. Navigate to:

4. Certificates, Identifiers & Profiles → Keys

5. Click + to create a new key

6. Enter:

7. Key Name: Example: Ecall Sign In

8. Enable service:

9. ✅ Sign in with Apple

10. Click Continue → Register

11. Download the key file: AuthKey_XXXXXXXXXX.p8

⚠️ Important - .p8 file can be downloaded only once - Apple does not store it - Back it up immediately in a secure location

2.2 Create Certificate Signing Request (CSR) on macOS¶

Action¶

1. Open Keychain Access

2. From the menu bar, select:

3. Keychain Access → Certificate Assistant → Request a Certificate From a Certificate Authority…

4. Fill in the form:

5. User Email Address: Your Apple ID email
6. Common Name: Company or app name (e.g. YourCompany)

7. CA Email Address: (leave empty)

8. Under Request is, select:

9. ✅ Saved to disk

10. Click Continue

11. Save the file (example): ApplePushCertRequest.certSigningRequest

Expected Result¶

• A .certSigningRequest (CSR) file is created on your machine
• This file will be uploaded to Apple Developer Portal in the next step

⚠️ Important Do NOT choose "Emailed to the CA". Always use Saved to disk for Apple certificates.

2.3 Create Push Notification Certificate on Apple Developer Portal¶

Action¶

1. Go to Apple Developer Certificates page:

2. 👉 https://developer.apple.com/account/resources/certificates/add

3. Under Services, select:

4. ✅ Apple Push Notification service SSL (Sandbox & Production)

5. Click Continue

6. Choose App ID (bundle app)

7. Upload the CSR file created in Step 2.2

8. Click Continue → Download

Expected Result¶

• A Push certificate (aps.cer) is downloaded
• This certificate supports both Sandbox & Production
• It will be used for standard push notifications

2.4 Create VoIP Push Certificate¶

Action¶

1. Repeat the same process:

2. Go to Certificates → Add

3. Select:

4. ✅ VoIP Services Certificate

5. Choose Same App ID (bundle app)

6. Upload the same CSR file

7. Download the VoIP certificate

Expected Result¶

• A VoIP Services certificate (voip.cer) is downloaded
• This certificate is required for CallKit incoming calls

📞 Without VoIP Push, incoming calls will not wake the app in background.

2.5 Install Certificates & Export .p12¶

Action¶

1. Double-click each downloaded .cer file to install into Keychain Access

2. Open Keychain Access

3. Locate the certificate + private key pair:

4. Apple Push Services

5. VoIP Services

6. Click the ▼ (disclosure arrow) to expand the certificate.

7. Select both rows at the same time:

8. the certificate row (e.g. Apple Push Services: <bundle id> / VoIP Services: <bundle id>)

9. the private key row under it (e.g. … private key)

10. Right-click (or Control-click) on the selection → Export 2 items…

11. Export as:

12. push_cert.p12

13. voip_cert.p12

14. Set and remember a password for each .p12

Expected Result¶

• You have:
• push_cert.p12
• voip_cert.p12
• Passwords are known and ready for upload

2.6 Upload Certificates to ECall Partner Dashboard¶

Action¶

1. Go back to ECall Partner Dashboard

2. Navigate to Account → Settings → Apple Configuration

3. Upload:

4. Apple Push Cert (.p12) + password
5. Apple VoIP Cert (.p12) + password

Expected Result¶

• Apple Push & VoIP services are fully configured
• Incoming call notifications will work correctly

3. Retrieve API Credentials & Configure Apple Integration¶

This step collects all credentials required for iOS integration, including ECall API credentials and Apple authentication & push certificates.

3.1 Retrieve ECall API Credentials¶

Action¶

1. Log in to the Partner Dashboard

2. Navigate to:

3. Account → Settings

4. 👉 http://ecall.org/admin/profile/settings

5. In App Configuration, copy the following values:

6. API ID
7. API Hash

Expected Result¶

• You have both:
• APP_API_ID
• APP_API_HASH
• These credentials will be used in the iOS project to authenticate with the ECall backend

🔒 Security Notice - API ID and API Hash are sensitive credentials - Do NOT commit them to GitHub - Do NOT hardcode them in source code - Store them only in Config.local.xcconfig (gitignored)

3.2 Upload Apple Credentials to ECall Partner Dashboard¶

This step binds all Apple credentials (Login, Push, VoIP) to your ECall partner application.

Action¶

1. In Partner Dashboard, navigate to:

2. Account → Settings → Apple Configuration

3. Fill in the following fields:

Apple Login

APNs

VoIP Push

1. Click Save / Update

Expected Result¶

• Apple Login is enabled
• APNs Push is enabled
• VoIP Push is enabled
• Incoming calls can be delivered via CallKit

3.3 OTP Delivery Configuration (SMTP & Twilio)¶

This section configures how OTP codes are delivered to users, via Email (SMTP) and/or Phone (Twilio SMS).

ECall supports Email OTP, SMS OTP, or both, depending on partner configuration.

3.3.1 SMTP Configuration (Email OTP)¶

SMTP configuration defines the sender email address used when sending OTP via email.

Fields

Behavior When SMTP Is Configured

• OTP emails are sent from the partner's SMTP email
• Sender name and address are derived from SMTP account

Fallback Behavior

⚠️ If SMTP configuration is left empty - OTP emails will be sent using the ECall default system email: - E2EE Call Support <[email protected]> - No email delivery is blocked - This is a safe default for partners who do not want to manage SMTP

✅ Recommended: Partners who want custom sender branding should configure SMTP.

3.3.2 Twilio Configuration (SMS OTP)¶

Twilio configuration enables OTP delivery via phone number (SMS).

Required Fields

Behavior When Twilio Is Configured

• Users can receive OTP via SMS
• The login UI will show:
• Continue with Phone
• Continue with Email

Behavior When Twilio Is NOT Configured

⚠️ If Twilio configuration is empty - SMS OTP is automatically disabled - The option "Continue with Phone" is hidden from UI - Only Email OTP is available

This behavior is controlled dynamically via:

GET https://api.your_app.org/app/api/app-config

The backend returns app configuration flags, and the client UI adapts automatically.

✅ This is by design, not a UI bug.

3.4 Configure App Update Policy (Server-Driven Updates)¶

ECall uses a Server-Driven Update architecture. Because of this, you do not rely entirely on standard App Store auto-updates. You enforce app updates using the ECall Partner Dashboard.

Action¶

1. In the Partner Dashboard, navigate to:

2. Account → Settings → Version

3. Configure the following fields:

Update Modes Explained¶

• 🚨 Force: Mandatory update. The app renders a blocking, full-screen UI. The user must update via the App Store to continue. Use this if the old version has critical bugs or breaking API changes.
• 👋 Soft: Optional update. The app displays an alert. If the user taps "Later", the alert is dismissed. It will not bother the user again until you increase the Latest App Version on the dashboard. Use this for standard feature releases.
• 🤫 None: Silent update. No popup is shown. The app functions normally. Use this when rolling out minor typo fixes, or during Apple's Phased Release until you confirm the new version is completely stable.

Expected Result¶

When you update the configuration, all active iOS clients will detect it (both at launch and when returning from the background). Clients running a version older than Latest App Version will automatically show the corresponding Force/Soft UI according to the policy you set.

3.5 Configure Telemetry & Crash Analytics¶

The ECall architecture natively supports both Apple's built-in crash reporting and Firebase Crashlytics/Analytics.

Apple Native Analytics (Organizer)¶

Because each partner signs the application with their own Apple Developer Account and unique Bundle ID, Apple automatically segregates crash reports. You can view native crashes directly in Xcode → Window → Organizer → Crashes. We highly encourage partners to review these logs and contribute hotfixes back to the open-source repository if they identify bugs.

Firebase Crashlytics & Analytics¶

The iOS codebase uses an automated "Inject Dynamic Firebase Config" build script. It dynamically injects the correct Firebase configuration at compile time based on the active PRODUCT_BUNDLE_IDENTIFIER.

Depending on your data privacy and business requirements, you must choose ONE of the following reporting models:

Mode A: Centralized (Core-Managed Firebase)

Recommended for partners who want a hands-off approach. - Action: You only provide the Core Team with your matching Bundle ID. - Flow: The ECall Core Team registers your app inside the master ECall Firebase Project, generates the configuration, and manages the codebase injection. - Data Access: Crash reports and analytics flow into the central ECall Firebase dashboard. The core team monitors and resolves issues proactively.

Mode B: Decentralized (Partner-Managed Firebase)

Recommended for enterprise partners requiring strict Data Isolation. - Action: 1. Create your own project on the Firebase Console. 2. Register an iOS App using your specific Bundle ID. 3. Download the GoogleService-Info.plist file. 4. Send this file to the ECall Core Team. - Flow: The Core Team will add your file to the repository (e.g., GoogleService-Info-YourBrand.plist) and update the injection script to map it to your Bundle ID. - Data Access: You have 100% exclusive access to your own Crashlytics and Analytics dashboards in real-time. No crash data regarding your app flows to the ECall core servers.

4. Configure iOS Project (Xcode)¶

This step configures the iOS source code to use the credentials prepared above.

4.1 Configure API Credentials via Config.local.xcconfig¶

The project uses .xcconfig files to manage sensitive credentials locally without committing them to Git.

Action¶

1. In the project root, copy the example file:

   cp Config.local.example.xcconfig Config.local.xcconfig
   

2. Open Config.local.xcconfig and fill in your real values:

   SLASH = /
   
   APP_API_ID = your_api_id_from_dashboard
   APP_API_HASH = your_api_hash_from_dashboard
   BASE_DOMAIN = your_app.org
   BUNDLE_URL_SCHEME = your_bundle_url_scheme
   GOOGLE_CLIENT_ID = your_google_client_id.apps.googleusercontent.com
   GOOGLE_URL_SCHEME = com.googleusercontent.apps.your_google_client_id
   APP_STORE_ID = your_app_store_id
   SHARE_URL = https:$(SLASH)/your_app_url
   

3. Open ecall.xcworkspace in Xcode

4. Verify: Go to Build Settings → Levels view to confirm values from Config File column are resolved correctly

⚠️ URL Note In .xcconfig files, // is treated as a comment. For URLs, always use: https:$(SLASH)/domain.com/path

Expected Result¶

• API credentials are injected at build time via xcconfig
• App can authenticate with ECall backend
• Config.local.xcconfig does NOT appear in git status (gitignored)

🔒 Security Notice - Never hardcode credentials in source files - Config.local.xcconfig is already in .gitignore - Each developer must create their own copy from the example file

⚠️ Do NOT modify the following: - API base URLs - Socket / Janus endpoints - Encryption / E2EE logic - Call signaling flow

These components are managed by the ECall core system. Changing them may break security and compatibility.

4.2 Build & Run on Real Device¶

Action¶

1. Select a physical iOS device

2. Build & Run the app

3. Test:

4. App launch
5. Login (Apple ID)
6. Incoming call (VoIP Push)
7. CallKit UI appears

Expected Result¶

• App launches successfully
• Incoming calls work in background & locked screen

5. Final Pre-Submission Checklist¶

Support¶

For technical support, contact: - Email: [email protected] - Portal: https://ecall.org/ - Documentation: https://docs.ecall.org