QR Code Integration
Learn how to implement UIP authentication with seamless device detection and QR code flows for optimal user experience.
How UIP Authentication Works
UIP's authentication flow adapts to the user's device context. The key is asking users upfront whether they want to authenticate on their current device or another device, eliminating guesswork and ensuring the best user experience.
Mobile Flow
User is on mobile and wants to authenticate on this device � UIP opens the mobile app directly, no QR code needed.
Desktop Flow
User is on desktop or wants to use another device � UIP generates a QR code to scan with their mobile UIP app.
� Best Practice: Always Ask First
Before making any API calls, present users with a choice: "Authenticate on this device" or "Authenticate with another device". This prevents failed attempts and ensures the optimal flow every time.
Why This Matters:
- " Eliminates device detection errors and edge cases
- " Respects user preference (they might want to use a different device)
- " Provides clear user intent for your API integration
- " Reduces friction and improves conversion rates
Implementation Flow
Present Device Choice
Show users two clear options before initiating authentication:
Make API Request
Call the UIP API with the appropriate parameters based on user choice:
// For mobile/same device flow
POST /api/v1/identify
{
"device_type": "mobile",
"redirect_url": "myapp://uip-callback",
"webhook_url": "https://myapp.com/webhooks/uip"
}
// For desktop/QR code flow
POST /api/v1/identify
{
"device_type": "desktop",
"webhook_url": "https://myapp.com/webhooks/uip"
}Handle API Response
UIP returns different response formats based on the device type:
Mobile Response
{
"type": "redirect",
"app_url": "uip://identify/abc123",
"session_id": "session_abc123"
}Desktop Response
{
"type": "qr_code",
"qr_image": "data:image/png;base64...",
"session_id": "session_abc123"
}Display Appropriate UI
Show the right interface based on the response type:
Mobile: Redirect to App
Opening UIP app...
Desktop: Show QR Code
Scan with UIP app
Receive Webhook Confirmation
All communication after the initial API call is handled through webhooks. UIP will send you the authentication result:
POST https://myapp.com/webhooks/uip
{
"event": "authentication_completed",
"session_id": "session_abc123",
"status": "success",
"user_data": {
"uip_id": "uip_1234567890",
"verified": true,
"name": "John Doe",
"age_verified": true
},
"timestamp": "2024-01-15T10:30:00Z"
}Complete Implementation Example
// JavaScript implementation
class UIPAuth {
constructor(apiKey) {
this.apiKey = apiKey;
this.baseUrl = 'https://auth.api.uip.id';
}
async startAuthentication(deviceChoice) {
const payload = {
device_type: deviceChoice, // 'mobile' or 'desktop'
webhook_url: 'https://myapp.com/webhooks/uip'
};
if (deviceChoice === 'mobile') {
payload.redirect_url = 'myapp://uip-callback';
}
const response = await fetch(`${this.baseUrl}/v1/identify`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
});
const data = await response.json();
if (data.type === 'redirect') {
// Mobile flow: redirect to UIP app
window.location.href = data.app_url;
} else if (data.type === 'qr_code') {
// Desktop flow: show QR code
this.displayQRCode(data.qr_image);
}
return data.session_id;
}
displayQRCode(qrImageData) {
const img = document.createElement('img');
img.src = qrImageData;
img.alt = 'UIP Authentication QR Code';
const container = document.getElementById('qr-container');
container.innerHTML = '';
container.appendChild(img);
}
}
// Usage
const uip = new UIPAuth('your-api-key');
document.getElementById('auth-this-device').addEventListener('click', () => {
uip.startAuthentication('mobile');
});
document.getElementById('auth-qr-code').addEventListener('click', () => {
uip.startAuthentication('desktop');
});Webhook Handling
After the user completes authentication in their UIP app, all communication happens through webhooks. This ensures real-time updates regardless of the user's device or network conditions.
// Express.js webhook handler
app.post('/webhooks/uip', express.json(), (req, res) => {
const { event, session_id, status, user_data } = req.body;
if (event === 'authentication_completed') {
if (status === 'success') {
// User successfully authenticated
console.log('User authenticated:', user_data);
// Update your application state
updateUserSession(session_id, user_data);
// Notify frontend via WebSocket, SSE, etc.
notifyFrontend(session_id, { success: true, user: user_data });
} else {
// Authentication failed or was cancelled
console.log('Authentication failed for session:', session_id);
notifyFrontend(session_id, { success: false });
}
}
res.status(200).send('OK');
});=� Pro Tip: Real-time Updates
Use WebSockets, Server-Sent Events, or polling to update your frontend when the webhook receives the authentication result. This provides instant feedback to users.