Інтеграція Google Wallet для перепусток у мобільному додатку

Інтеграція Google Wallet для пропусків в мобільних додатках

Пропуск у Google Wallet — це GenericObject на основі GenericClass. Generic — універсальний тип для всього, що не є квитком, посадочним талоном або купоном: пропуск на парковку, членська карта, карта лояльності, абонемент, робочий бейдж. В API це найбільш гнучкий тип: структура полів задається довільно через textModulesData, linksModuleData та imageModulesData.

Структура GenericObject

def create_access_pass(class_id: str, holder_name: str,
                        pass_id: str, access_level: str) -> dict:
    issuer_id = "YOUR_ISSUER_ID"

    return {
        "id": f"{issuer_id}.pass_{pass_id}",
        "classId": class_id,
        "state": "ACTIVE",
        "cardTitle": {
            "defaultValue": {"language": "uk", "value": "Пропуск сотрудника"}
        },
        "subheader": {
            "defaultValue": {"language": "uk", "value": "Рівень доступу"}
        },
        "header": {
            "defaultValue": {"language": "uk", "value": access_level}  # "A1 — все зоны"
        },
        "textModulesData": [
            {
                "header": "Власник",
                "body": holder_name,
                "id": "holder"
            },
            {
                "header": "ID пропуска",
                "body": pass_id,
                "id": "pass_id"
            },
            {
                "header": "Дійсний до",
                "body": "31.12.2024",
                "id": "valid_until"
            }
        ],
        "barcode": {
            "type": "QR_CODE",
            "value": pass_id,
            "alternateText": pass_id[:8].upper()
        },
        "heroImage": {
            "sourceUri": {
                "uri": "https://yourcompany.com/office-photo.jpg"
            }
        },
        "validTimeInterval": {
            "start": {"date": "2024-01-01T00:00:00Z"},
            "end": {"date": "2024-12-31T23:59:59Z"}
        },
        "notifications": {
            "expiryNotification": {
                "enableNotification": True
            }
        }
    }

notifications.expiryNotification — Google Wallet автоматично сповіщає користувача за 3 дні до закінчення. Не потрібна додаткова серверна логіка.

GenericClass: мінімальна конфігурація

def create_generic_class(class_suffix: str) -> dict:
    issuer_id = "YOUR_ISSUER_ID"

    return {
        "id": f"{issuer_id}.{class_suffix}",
        "issuerName": "Your Company",
        "reviewStatus": "UNDER_REVIEW",
        "enableSmartTap": False,  # True лише якщо є NFC-ридери
        "multipleDevicesAndHoldersAllowedStatus": "ONE_USER_ONE_DEVICE"
    }

ONE_USER_ONE_DEVICE — пропуск неможна передати іншому користувачу або зберегти на кількох пристроях одного акаунта. Для корпоративних пропусків це правильне обмеження.

Створення класу через API перед першим JWT

Клас потрібно створити один раз через API — у JWT можна лише вбудувати об'єкт, клас через JWT не створюється:

from googleapiclient.discovery import build
from google.oauth2 import service_account

def ensure_generic_class_exists(class_data: dict) -> bool:
    creds = service_account.Credentials.from_service_account_file(
        'service-account.json',
        scopes=['https://www.googleapis.com/auth/wallet_object.issuer']
    )
    service = build('walletobjects', 'v1', credentials=creds)

    try:
        service.genericclass().get(resourceId=class_data["id"]).execute()
        return True  # уже існує
    except HttpError as e:
        if e.resp.status == 404:
            service.genericclass().insert(body=class_data).execute()
            return True
    return False

Android: повний flow

class PassActivity : AppCompatActivity() {
    private val walletClient by lazy {
        Wallet.getWalletClient(this, WalletOptions.Builder()
            .setEnvironment(WalletConstants.ENVIRONMENT_PRODUCTION)
            .build())
    }

    private val savePassLauncher = registerForActivityResult(
        ActivityResultContracts.StartIntentSenderForResult()
    ) { result ->
        when (result.resultCode) {
            RESULT_OK -> {
                analytics.track("wallet_pass_added")
                binding.addToWalletBtn.text = "Вже в Wallet"
                binding.addToWalletBtn.isEnabled = false
            }
            RESULT_CANCELED -> Unit
        }
    }

    fun onAddToWalletClicked() {
        viewModel.generatePassJwt().observe(this) { jwt ->
            walletClient.savePassesViaIntent(
                SavePassesRequest.newBuilder().setJwt(jwt).build()
            ) { result ->
                result.intentSender?.let {
                    savePassLauncher.launch(IntentSenderRequest.Builder(it).build())
                } ?: run {
                    // Вже додано
                    binding.addToWalletBtn.isEnabled = false
                }
            }
        }
    }
}

Оновлення пропуска (зміна рівня доступу)

def update_pass_access_level(object_id: str, new_level: str):
    service = build('walletobjects', 'v1', credentials=creds)
    service.genericobject().patch(
        resourceId=object_id,
        body={
            "header": {
                "defaultValue": {"language": "uk", "value": new_level}
            }
        }
    ).execute()

Зміни з'являються в Wallet користувача протягом кількох хвилин — без переіздання пропуска.

Тривалість

1–3 дні. Базовий пропуск з QR-кодом та автоматичним сповіщенням про закінчення — 1,5 дня. Оновлення через API + обмеження на передачу між пристроями — 2–3 дні. Вартість розраховується індивідуально.