iOS License Management
Documento tecnico che descrive come vengono gestite le licenze nell'app iOS, inclusi i punti di controllo, upgrade/downgrade, e integrazione con Apple StoreKit 2.
Architettura
┌─────────────────────────────────────────────────────────────────────────────┐
│ iOS App (StoreKit 2) │
│ │
│ ┌─────────────────┐ ┌──────────────────┐ ┌───────────────────────┐ │
│ │ StoreManager │ │ PlanSelection │ │ SubscriptionManagement│ │
│ │ - purchase() │ │ - device count │ │ - status display │ │
│ │ - restore() │ │ - period select │ │ - upgrade/downgrade │ │
│ └────────┬────────┘ └────────┬─────────┘ └───────────┬───────────┘ │
│ │ │ │ │
│ └──────────────────────┼──────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ ApiClient │ │
│ │ - getLicense │ │
│ │ - getStatus │ │
│ └──────┬───────┘ │
└──────────────────────────────────┼──────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ Backend │
│ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Billing Service │◄─────────────│ Apple S2S v2 Webhook │ │
│ │ │ │ POST /api/billing/webhooks/apple │ │
│ │ subscriptions │ └─────────────────────────────────────┘ │
│ │ - user_id │ │
│ │ - plan_id │◄─── plan_id = "annual_3" (3 dispositivi, annuale) │
│ │ - status │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Devices Service │ │
│ │ │ │
│ │ - active count │◄─── Quanti dispositivi ha l'utente attivi │
│ │ - suspended │◄─── Dispositivi sospesi per limite licenze │
│ └─────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────┘
Piano di Licenze
Le licenze sono codificate nel plan_id:
| plan_id | Periodo | Dispositivi |
|---|---|---|
monthly_1 | Mensile | 1 |
monthly_2 | Mensile | 2 |
annual_3 | Annuale | 3 |
annual_5 | Annuale | 5 |
Formato: {periodo}_{numero_dispositivi}
Punti di Controllo Licenze
1. Aggiunta Dispositivo (DevicesListView)
Quando l'utente preme "+" per aggiungere un nuovo dispositivo:
// DevicesListView.swift - checkLicenseAndShowAddDevice()
1. Chiama ApiClient.getLicenseStatus()
2. Controlla:
- Se allowed == 0 → Mostra PlanSelectionView (reason: .noLicense)
- Se active >= allowed → Mostra PlanSelectionView (reason: .upgradeLicense)
- Altrimenti → Mostra AddDeviceView
File: VislaGPS/Views/DevicesListView.swift:205-247
2. Riattivazione Dispositivo (DeviceDetailView)
Quando l'utente vuole riattivare un dispositivo sospeso:
// DeviceDetailView.swift - reactivateDevice()
1. Chiama ApiClient.getLicenseStatus()
2. Se active >= allowed → Mostra SubscriptionRequiredModal
3. Altrimenti → Procedi con riattivazione
File: VislaGPS/Views/DeviceDetailView.swift
3. Gestione Piano (SubscriptionManagementView)
Accessibile da Impostazioni → "Gestisci Piano":
// SubscriptionManagementView.swift
Mostra:
- Status abbonamento (Attivo/Scaduto)
- Provider (Apple/Stripe)
- Utilizzo licenze (X/Y attive)
- Pulsante "Modifica Piano" → PlanSelectionView
- Pulsante "Disdici Abbonamento" → App Store
File: VislaGPS/Views/SubscriptionManagementView.swift
Flusso Upgrade/Downgrade
Upgrade (es. da 1 a 3 dispositivi)
┌─────────────────┐
│ User ha 1 lic. │
│ Vuole aggiungere│
│ 2° dispositivo │
└────────┬────────┘
│
▼
┌─────────────────┐
│ + tapped │
│ getLicenseStatus│
│ active >= allowed│
└────────┬────────┘
│
▼
┌─────────────────┐
│ PlanSelectionView│
│ reason: upgrade │
│ current: 1 │
│ default: 2 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Pulsante mostra │
│ "Aumenta Licenze"│
│ (non "Abbonati")│
└────────┬────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐
│ StoreKit 2 │────▶│ Apple processa │
│ purchase() │ │ upgrade prorata │
└─────────────────┘ └────────┬────────┘
│
▼
┌─────────────────┐
│ Webhook S2S v2 │
│ DID_CHANGE_* │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Backend aggiorna│
│ plan_id: "X_3" │
└─────────────────┘
Downgrade (es. da 3 a 1 dispositivo)
┌─────────────────┐
│ User ha 3 lic. │
│ Vuole ridurre │
│ a 1 licenza │
└────────┬────────┘
│
▼
┌─────────────────┐
│ PlanSelectionView│
│ Seleziona 1 │
│ pulsante: │
│ "Riduci Licenze"│
└────────┬────────┘
│
▼
┌─────────────────┐
│ Controllo: │
│ activeDevices=2 │
│ selectedPlan=1 │
│ │
│ ERRORE! Non puoi│
│ ridurre a 1 con │
│ 2 dispositivi │
│ attivi │
└─────────────────┘
Messaggio: "Hai 2 dispositivi attivi. Per passare al piano da 1
dispositivo, devi prima sospendere o rimuovere i dispositivi in eccesso."
Protezione Downgrade: L'utente non può ridurre le licenze a meno di quanti dispositivi attivi ha.
PlanSelectionView - Logica Pulsante
// PlanSelectionView.swift
private var purchaseButtonText: String {
if isChangingPlan {
if selectedDevices == currentDevices {
return "Piano Attuale" // Grigio, disabilitato
} else if selectedDevices > currentDevices {
return "Aumenta Licenze" // Blu, attivo
} else {
return "Riduci Licenze" // Blu, attivo (con controllo)
}
}
return "Abbonati Ora" // Nuovo abbonamento
}
| Stato | currentDevices | selectedDevices | Pulsante |
|---|---|---|---|
| Nuovo utente | nil/0 | 1 | "Abbonati Ora" |
| Ha 1 lic | 1 | 1 | "Piano Attuale" (disabled) |
| Ha 1 lic | 1 | 2 | "Aumenta Licenze" |
| Ha 3 lic | 3 | 1 | "Riduci Licenze" |
| Ha 3 lic | 3 | 5 | "Aumenta Licenze" |
Integrazione Apple StoreKit 2
appAccountToken
L'app passa l'user_id ad Apple in formato UUID:
// StoreManager.swift
let appAccountToken = UUID(uuidString:
String(format: "%08x-0000-0000-0000-000000000000", userId)
) ?? UUID()
// Esempio: userId=2 → "00000002-0000-0000-0000-000000000000"
Webhook Backend
Il billing service estrae l'user_id dall'appAccountToken:
# apple_provider.py - _extract_user_id()
def _extract_user_id(self, app_account_token: str) -> int:
# Parse UUID format: "00000002-0000-0000-0000-000000000000"
parts = app_account_token.split("-")
user_id_hex = parts[0] # "00000002"
return int(user_id_hex, 16) # → 2
Configurazione App Store Connect
- Production URL:
https://api.vislagps.com/api/billing/webhooks/apple - Sandbox URL:
https://api-dev.vislagps.com/api/billing/webhooks/apple - Version: 2 (S2S v2)
Tempi di Aggiornamento
Sandbox vs Produzione
| Operazione | Sandbox | Produzione |
|---|---|---|
| Nuovo acquisto | ~1 min webhook | Secondi |
| Upgrade | Attende scadenza periodo (3-5 min) | Immediato + prorata |
| Downgrade | Attende scadenza | Al rinnovo successivo |
| Cancellazione | Attende scadenza | Al rinnovo successivo |
Nota Importante: In sandbox gli upgrade sembrano lenti perché Apple aspetta la scadenza del periodo (3-5 minuti per mensile). In produzione, gli upgrade sono immediati con calcolo prorata del credito.
API Endpoints Utilizzati
GET /api/devices/license/status
Restituisce lo stato licenze dell'utente.
{
"allowed": 3, // Licenze acquistate
"active": 2, // Dispositivi attivi
"suspended": 0 // Dispositivi sospesi
}
GET /api/billing/subscriptions/check/{user_id}
Restituisce lo stato abbonamento.
{
"is_subscribed": true,
"has_active_subscription": true,
"status": "ACTIVE",
"provider": "apple",
"plan_id": "annual_3",
"devices": 3,
"expires_at": "2026-01-15T00:00:00Z"
}
File Chiave
| File | Responsabilità |
|---|---|
StoreManager.swift | Gestione acquisti StoreKit 2 |
PlanSelectionView.swift | UI selezione piano, logica upgrade/downgrade |
SubscriptionManagementView.swift | UI gestione abbonamento esistente |
DevicesListView.swift | Controllo licenze prima di aggiungere dispositivo |
DeviceDetailView.swift | Controllo licenze per riattivazione |
SubscriptionRequiredModal.swift | Modal per acquisto licenze aggiuntive |
ApiClient.swift | Chiamate API per license/subscription status |
Troubleshooting
"Acquisto completato ma licenze non aggiornate"
- In Sandbox: Aspetta 3-5 minuti per il webhook
- Controlla i log del billing service:
docker logs billing --tail 100 - Verifica che il webhook arrivi: cerca "Received Apple webhook"
- Verifica estrazione user_id: cerca "Extracted user_id"
"Non posso ridurre le licenze"
L'utente deve prima sospendere/rimuovere dispositivi fino ad averne meno del piano target.
"Disdici abbonamento non funziona"
Il pulsante apre l'App Store. La cancellazione effettiva avviene là. Il backend riceverà il webhook quando Apple processa la cancellazione.