Direct API Integration Guide

This guide provides complete implementation details for integrating directly with ULink's API endpoints. If you're looking for a quick overview, see the API Reference first.

Prerequisites

• ULink account and API key (get one here)
• Understanding of HTTP requests and JSON
• Secure storage mechanism for tokens (SharedPreferences, UserDefaults, etc.)

Integration Flow

ULink requires two steps for proper tracking:

1. Installation Tracking: Identify unique app installations
2. Session Management: Track when users are active

Follow this sequence: Installation → Session → Normal API usage

Implementation Steps

1. Initial Setup

# Set your API key
export ULINK_API_KEY="your-api-key-here"
export ULINK_BASE_URL="https://api.ulink.ly"

2. Track Installation (Required)

When to call: Once per app installation/device, or when your installation token expires.

curl -X POST "$ULINK_BASE_URL/sdk/installations/track" \
  -H "X-App-Key: $ULINK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-ULink-Client: api-direct" \
  -H "X-ULink-Client-Version: 1.0.0" \
  -H "X-ULink-Client-Platform: ios" \
  -d '{
    "installationId": "unique-installation-id-from-your-app",
    "deviceId": "device-identifier",
    "deviceModel": "iPhone 15 Pro",
    "deviceManufacturer": "Apple",
    "osName": "iOS",
    "osVersion": "17.0",
    "appVersion": "1.0.0",
    "appBuild": "100",
    "language": "en",
    "timezone": "America/New_York"
  }'

Response includes installation token:

{
  "success": true,
  "installationId": "db-record-id",
  "isNew": true,
  "installationToken": "eyJhbGciOiJIUzI1NiIs..."
}

Response Headers:

X-Installation-Token: eyJhbGciOiJIUzI1NiIs...

⚠️ Important: Save the installationToken securely in your app (SharedPreferences, UserDefaults, etc.). This token identifies your installation for 90-180 days.

3. Start Session (Required)

When to call: When user opens your app or becomes active.

curl -X POST "$ULINK_BASE_URL/sdk/sessions/start" \
  -H "X-App-Key: $ULINK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Installation-Token: eyJhbGciOiJIUzI1NiIs..." \
  -H "X-ULink-Client: api-direct" \
  -H "X-ULink-Client-Version: 1.0.0" \
  -H "X-ULink-Client-Platform: ios" \
  -d '{
    "installationId": "unique-installation-id-from-your-app",
    "deviceOrientation": "portrait",
    "networkType": "wifi",
    "batteryLevel": 85,
    "isCharging": false
  }'

Response:

{
  "success": true,
  "sessionId": "session-uuid"
}

4. Create Links (Optional)

curl -X POST "$ULINK_BASE_URL/sdk/links" \
  -H "X-App-Key: $ULINK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Installation-Token: eyJhbGciOiJIUzI1NiIs..." \
  -d '{
    "type": "unified",
    "slug": "my-custom-link",
    "fallbackUrl": "https://example.com",
    "iosUrl": "https://apps.apple.com/app/id123",
    "androidUrl": "https://play.google.com/store/apps/details?id=com.app"
  }'

Response:

{
  "id": "link-id",
  "slug": "my-custom-link",
  "shortUrl": "https://yourdomain.com/my-custom-link",
  "type": "unified", 
  "fallbackUrl": "https://example.com",
  "createdAt": "2024-01-01T00:00:00Z"
}

5. Resolve Links (Optional)

curl -X GET "$ULINK_BASE_URL/sdk/resolve?url=https://yourdomain.com/your-slug" \
  -H "X-App-Key: $ULINK_API_KEY" \
  -H "X-Installation-Token: eyJhbGciOiJIUzI1NiIs..." \
  -H "X-ULink-Client: api-direct" \
  -H "X-ULink-Client-Version: 1.0.0" \
  -H "X-ULink-Client-Platform: ios"

Response:

{
  "id": "link-id",
  "slug": "your-slug", 
  "type": "unified",
  "fallbackUrl": "https://example.com",
  "iosUrl": "https://apps.apple.com/app/id123",
  "androidUrl": "https://play.google.com/store/apps/details?id=com.app"
}

Response Headers:

X-Installation-Token: eyJhbGciOiJIUzI1NiIs...  # Refreshed token if needed
X-ULink-Context: installation-attached|auto-installed|none
X-ULink-Warning: missing_device_id  # Only if no installation context

6. End Session (Recommended)

When to call: When user backgrounds the app or becomes inactive.

curl -X POST "$ULINK_BASE_URL/sdk/sessions/{sessionId}/end" \
  -H "X-App-Key: $ULINK_API_KEY" \
  -H "X-Installation-Token: eyJhbGciOiJIUzI1NiIs..."

Response:

{
  "success": true
}

Installation Token Management

What is an Installation Token?

An installation token is a JWT (JSON Web Token) that:

• Securely identifies your app installation
• Expires after 90-180 days
• Eliminates the need to send installationId in every request
• Prevents duplicate installations when upgrading client versions

Token Management Flow

1. App Launch: Check for saved token
2. No Token: Call /sdk/installations/track to get one
3. Has Token: Use it in API requests
4. Token Expired: Refresh by calling /sdk/installations/track again

Required Headers for Direct Integration

All ULink SDK endpoints require these headers:

# Required
X-App-Key: your-api-key-here
Content-Type: application/json

# Recommended for analytics and proper tracking  
X-ULink-Client: api-direct
X-ULink-Client-Version: 1.0.0
X-ULink-Client-Platform: ios|android|web|server

# Optional (for old SDK compatibility)
X-Installation-Id: your-installation-id  # Fallback if no token
X-Device-Id: your-device-id  # For legacy SDK versions

# Required after installation tracking
X-Installation-Token: eyJhbGciOiJIUzI1NiIs...

Error Handling

Common Error Responses

Status	Error	Solution
401	Invalid or missing API key	Check X-App-Key header
400	API key is required	Include valid X-App-Key header
400	URL parameter is required	Include url query parameter for resolve
404	Link with slug 'x' not found	Verify the URL/slug exists
403	Usage limit exceeded	Check your plan limits

Important Response Headers

X-Installation-Token: eyJhbGciOiJIUzI1NiIs...  # Save this token
X-ULink-Context: installation-attached|auto-installed|none
X-ULink-Warning: missing_device_id  # Installation context missing

Best Practices

1. Installation Tracking

• Call /sdk/installations/track once per app installation
• Save the returned token securely
• Refresh token only when it expires (90-180 days)

2. Session Management

• Start session when app becomes active
• End session when app goes to background
• Don't start multiple sessions simultaneously

3. Token Handling

• Always include X-Installation-Token in requests after tracking installation
• Automatically retry with fresh token on 401/428 errors
• Store token securely (SharedPreferences, UserDefaults, etc.)

4. Error Recovery

• Implement automatic retry for network failures
• Refresh tokens on authentication errors
• Queue operations when offline

Migration from Basic API Usage

If you're currently using only /sdk/resolve:

Add Installation Tracking

# First, track the installation
curl -X POST https://api.ulink.ly/sdk/installations/track \
  -H "X-App-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"installationId": "unique-id", ...}'

# Save the returned installationToken

Add Session Management

# Start session for active users
curl -X POST https://api.ulink.ly/sdk/sessions/start \
  -H "X-App-Key: YOUR_API_KEY" \
  -H "X-Installation-Token: SAVED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"installationId": "unique-id", ...}'

Updated Resolve Calls

# Now include the installation token
curl -X GET "https://api.ulink.ly/sdk/resolve?url=YOUR_URL" \
  -H "X-App-Key: YOUR_API_KEY" \
  -H "X-Installation-Token: SAVED_TOKEN"

Troubleshooting

Common Issues

"Installation context missing" warnings

Symptoms: Getting X-ULink-Warning: missing_device_id headers Solution: Always include X-Installation-Token or call /sdk/installations/track first

Sessions not tracking properly

Symptoms: Dashboard shows fewer active users than expected Solution: Ensure you're calling /sdk/sessions/start for active users

Link creation fails

Symptoms: 404 error when creating links Solution: Ensure your project has a verified domain configured

Token expiration errors

Symptoms: 401 or 428 errors after working for months Solution: Implement automatic token refresh when errors occur

Debug Checklist

• API key is valid and in X-App-Key header
• Installation tracking called at least once
• Installation token saved and included in requests
• Sessions started for active users
• Error handling with token refresh implemented

Next Steps

1. Implement the complete flow with installation tracking and session management
2. Test MAU tracking with a small user group
3. Monitor usage in the ULink dashboard
4. Consider an official SDK for automatic handling of these concerns

Support

• API Questions: API Reference
• SDK Options: SDK Overview
• Issues: Contact Support

Consider SDKs

Our official SDKs handle all this complexity automatically. This guide is for custom implementations only.