Sprawdzanie kluczy licencji z aplikacji w Node albo Go: limit urządzeń, wygaśnięcie i unieważnienie

Q: Czy można bezpiecznie umieścić klucz API w aplikacji desktopowej?

Tylko klucz, którego jedynym zakresem jest licenses:validate. Potrafi sprawdzać klucze i nic więcej.

Q: Czy kupujący może przenieść licencję na nowy komputer?

Tak, gdy zwolnisz jego urządzenia przez licenses.resetDevices ze swojego serwera albo narzędzia supportu.

Q: Co dzieje się z kluczem, gdy subskrypcja się kończy?

Od tej chwili sprawdzenie zwraca SUBSCRIPTION_INACTIVE.

Gdy Skalp generuje klucz licencji do każdej sprzedaży, twoja aplikacja sprawdza go jednym wywołaniem API. Odpowiedź mówi, czy klucz działa, a jeśli nie, to dlaczego: wygasł, został unieważniony po zwrocie, przekroczył limit urządzeń albo należy do subskrypcji, która się skończyła. Poniżej konfiguracja i kod dla Node, Go i zwykłego HTTP.

Ustaw produkt

Utwórz produkt i ustaw dostawę na klucz licencji. Każde zamówienie dostaje wtedy nowy klucz.
Ustaw limit urządzeń, jeśli jeden klucz ma działać tylko na kilku komputerach, i czas trwania, jeśli licencja ma wygasać po określonej liczbie dni. Zostaw czas trwania pusty dla licencji dożywotniej albo sprzedawaj produkt jako subskrypcję, żeby klucz działał, dopóki plan jest opłacony.
Utwórz klucz API z jednym zakresem: licenses:validate. Z samym tym zakresem klucz nie odczyta zamówień i niczego nie zmieni, więc może trafić do aplikacji.

Node

import { Skalp } from '@skalpgg/sdk'

const skalp = new Skalp({ apiKey: LICENSE_CHECK_KEY })

const result = await skalp.licenses.validate({
  key: enteredKey,
  hardwareId: machineId,
})

if (!result.valid) {
  showError(result.message)
} else {
  unlock(result.license?.expiresAt)
}

Pakiet działa w Node 20+, Bun, Deno i środowiskach edge. W przeglądarce z kluczem API odmawia startu, chyba że przekażesz dangerouslyAllowBrowser: true, więc sprawdzanie dla strony internetowej powinno działać na twoim serwerze.

Go

client := skalp.New(skalp.Options{APIKey: licenseCheckKey})

res, err := client.ValidateLicense(ctx, skalp.ValidateLicenseParams{
	Key:        enteredKey,
	HardwareID: machineID,
})
if err != nil {
	return err
}
if !res.Valid {
	return fmt.Errorf("license: %s", res.Message)
}

Każdy inny język

curl https://api.skalp.gg/v1/licenses/validate \
  -H "x-api-key: $SKALP_LICENSE_CHECK_KEY" \
  -H "content-type: application/json" \
  -d '{"key":"THE-BUYERS-KEY","hardwareId":"9f2c41..."}'

Dodaj do treści "productId", jeśli klucz z innego twojego produktu nie może odblokować tego.

Co znaczą kody

Kod	Znaczenie
`VALID`	Klucz działa. Odpowiedź zawiera też datę wygaśnięcia i liczbę używanych urządzeń.
`NOT_FOUND`	W twoim sklepie nie ma takiego klucza.
`PRODUCT_MISMATCH`	Klucz należy do innego produktu niż wysłany `productId`.
`LICENSING_DISABLED`	Dostawa produktu nie jest ustawiona na klucz licencji.
`REVOKED`	Zamówienie zostało zwrócone albo przegrało chargeback.
`SUSPENDED`	Licencja została zawieszona.
`EXPIRED`	Licencja minęła datę końcową.
`SUBSCRIPTION_INACTIVE`	Subskrypcja, do której należy klucz, się skończyła.
`DEVICE_LIMIT_REACHED`	Klucz jest już przypisany do tylu komputerów, ile pozwala produkt.

Limit urządzeń

Jeśli wysyłasz hardwareId, a produkt ma limit urządzeń, pierwsze sprawdzenie z nowego komputera przypisuje go do klucza. Sprawdzenia z przypisanych komputerów przechodzą, a nowy komputer ponad limit dostaje DEVICE_LIMIT_REACHED. Wysyłaj wartość, która na jednym komputerze się nie zmienia, i najpierw ją zahashuj, żeby żadne surowe dane sprzętu nie opuszczały komputera. Gdy kupujący wymieni komputer, twój serwer zwolni miejsca przez licenses.resetDevices. To wywołanie wymaga zakresu licenses:write, więc nigdy nie należy do samej aplikacji.

Praca offline

Sprawdzaj klucz przy starcie aplikacji i zapisuj ostatnią dobrą odpowiedź z datą. Gdy nie ma sieci, akceptuj zapisaną odpowiedź przez wybrany przez siebie okres, na przykład kilka dni, i sprawdź ponownie, gdy aplikacja wróci do sieci. Klucz unieważniony w międzyczasie nie przejdzie tego sprawdzenia.

Własna kopia kluczy

Jeśli wolisz sprawdzać klucze we własnym backendzie, bierz je z webhooka order.paid, który zawiera licencje zamówienia. Webhooki zwrotów i sporów powiedzą ci, kiedy klucz wyłączyć. Webhooki i API.

Najczęstsze pytania

Czy można bezpiecznie umieścić klucz API w aplikacji desktopowej?

Tylko klucz, którego jedynym zakresem jest licenses:validate. Potrafi sprawdzać klucze i nic więcej.

Czy kupujący może przenieść licencję na nowy komputer?

Tak, gdy zwolnisz jego urządzenia przez licenses.resetDevices ze swojego serwera albo narzędzia supportu.

Co dzieje się z kluczem, gdy subskrypcja się kończy?

Od tej chwili sprawdzenie zwraca SUBSCRIPTION_INACTIVE.

Muszę używać SDK?

Nie. Sprawdzenie to jeden POST po HTTPS z treścią w JSON, więc zadziała każdy język, który potrafi wysłać żądanie.