Синхронизация транзакций из кастомных сторов

Если вы продаёте подписки или встроенные покупки через кастомные сторы — например, Amazon Appstore, Microsoft Store или собственную платёжную платформу — вы можете синхронизировать эти транзакции с Adapty, чтобы автоматически управлять уровнями доступа и отслеживать выручку в аналитике.

В этом гайде вы узнаете, как связать покупки из кастомных сторов с Adapty через SDK и API.

Пример использования

Допустим, вы распространяете приложение через Amazon Appstore или создали собственный веб-магазин для прямых продаж. Когда пользователь совершает покупку на этих платформах, вы хотите:

Автоматически предоставить ему доступ к премиум-функциям в мобильном приложении
Отслеживать транзакцию в аналитике Adapty рядом с доходами из App Store и Google Play
Запускать интеграции и вебхуки так же, как для любой другой подписки

Именно для этого и нужна данная интеграция.

Шаг 1. Идентифицируйте пользователей

Adapty использует customer_user_id для идентификации пользователей на всех платформах.

Этот ID нужно создать один раз и передать как в мобильный SDK, так и в веб-бэкенд. Когда пользователи впервые регистрируются через приложение, можно передать customer_user_id при активации SDK. Если же SDK был активирован до этапа регистрации, используйте метод identify, чтобы создать новый профиль и привязать к нему customer_user_id.

Если вы идентифицируете пользователей после активации SDK, сначала будет создан анонимный профиль (без него SDK не может работать). Когда вы вызовете identify с customer user ID, будет создан новый профиль.

Это нормальное поведение, которое не влияет на точность аналитики. Подробнее здесь.

do {
    try await Adapty.identify("YOUR_USER_ID") // Unique for each user
} catch {
    // handle the error
}

// User IDs must be unique for each user
Adapty.identify("YOUR_USER_ID") { error in
    if let error {
        // handle the error
    }
}

Adapty.identify("YOUR_USER_ID") { error -> // Unique for each user
    if (error == null) {
        // successful identify
    }
}

// User IDs must be unique for each user
Adapty.identify("YOUR_USER_ID", error -> {
    if (error == null) {
        // successful identify
    }
});

try {
    await adapty.identify("YOUR_USER_ID"); // Unique for each user
    // successfully identified
} catch (error) {
    // handle the error
}

try {
  await Adapty().identify(customerUserId); // Unique for each user
} on AdaptyError catch (adaptyError) {
  // handle the error
} catch (e) {
}

Adapty.Identify("YOUR_USER_ID", (error) => { // Unique for each user
  if(error == null) {
    // successful identify
  }
});

Adapty.identify("YOUR_USER_ID") // Unique for each user
    .onSuccess {
        // successful identify
    }
    .onError { error ->
        // handle the error
    }

try {
  await adapty.identify({ customerUserId: "YOUR_USER_ID" });
  // successfully identified
} catch (error) {
  // handle the error
}

Шаг 2. Создайте продукты в кастомном сторе в дашборде Adapty

Чтобы Adapty мог сопоставлять транзакции кастомного стора с вашими продуктами, нужно добавить продукты и настроить для них данные кастомного стора.

Откройте Products в левом меню дашборда Adapty и нажмите Create product. Или нажмите на существующий продукт, чтобы отредактировать его.
Убедитесь, что выбран уровень доступа, который вы хотите предоставлять пользователям при покупке продукта.
Нажмите + и выберите Add a custom store.
Нажмите Create new custom store.

Задайте имя стора (например, «Amazon Appstore», «Microsoft Store» или «Web Store») и его ID. Нажмите Create custom store.

Затем нажмите Save changes, чтобы привязать продукт к пользовательскому стору.
Введите Store product ID для продукта, чтобы сопоставить его с продуктом в этом сторе. Затем нажмите Save.

Шаг 3. Синхронизация транзакций через API

Когда покупка завершается в вашем кастомном сторе, нужно синхронизировать её с Adapty через серверный API.

Этот вызов API выполнит следующее:

Запишет транзакцию в Adapty
Предоставит пользователю соответствующий уровень доступа
Запустит все настроенные интеграции и вебхуки
Отобразит транзакцию в вашей аналитике

Полная документация по методу — здесь.

curl --request POST \
  --url https://api.adapty.io/api/v2/server-side-api/purchase/set/transaction/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Api-Key YOUR_SECRET_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'adapty-customer-user-id: YOUR_CUSTOMER_USER_ID' \
  --data '{
  "purchase_type": "PRODUCT_PERIOD",
  "store": "YOUR_CUSTOM_STORE",
  "environment": "production",
  "store_product_id": "YOUR_STORE_PRODUCT_ID",
  "store_transaction_id": "STORE_TRANSACTION_ID",
  "store_original_transaction_id": "ORIGINAL_TRANSACTION_ID",
  "price": {
    "country": "COUNTRY_CODE",
    "currency": "CURRENCY_CODE",
    "value": "YOUR_PRICE"
  },
  "purchased_at": "2024-01-15T10:30:00Z"
}'

Важные параметры:

store: ID вашего кастомного стора из шага 2
store_product_id: ID продукта в сторе из шага 2
store_transaction_id: Уникальный идентификатор транзакции
purchased_at: Временная метка в формате ISO 8601, когда была совершена покупка
price: Сумма, уплаченная пользователем

Шаг 4. Проверьте доступ в приложении

После синхронизации транзакции профиль пользователя автоматически обновится с новым уровнем доступа.

Когда пользователь откроет ваше мобильное приложение, получите его профиль, чтобы проверить статус подписки и открыть доступ к premium-функциям.

do {
    let profile = try await Adapty.getProfile()

    if profile.accessLevels["YOUR_ACCESS_LEVEL"]?.isActive ?? false {
        // grant access to premium features
    }
} catch {
// handle the error
}

Adapty.getProfile { result in
    if let profile = try? result.get() {
        // check the access
        if profile.accessLevels["YOUR_ACCESS_LEVEL"]?.isActive ?? false {
            // grant access to premium features
        }
    }
}

Adapty.getProfile { result ->
    when (result) {
        is AdaptyResult.Success -> {
            val profile = result.value
            // check the access
            if (profile.accessLevels["YOUR_ACCESS_LEVEL"]?.isActive == true) {
                // grant access to premium features
            }
        }
        is AdaptyResult.Error -> {
            val error = result.error
            // handle the error
        }
    }
}

Adapty.getProfile(result -> {
    if (result instanceof AdaptyResult.Success) {
        AdaptyProfile profile = ((AdaptyResult.Success<AdaptyProfile>) result).getValue();
        // check the access
        if (profile.getAccessLevels().get("YOUR_ACCESS_LEVEL") != null && profile.getAccessLevels().get("YOUR_ACCESS_LEVEL").getIsActive()) {
            // grant access to premium features
        }

    } else if (result instanceof AdaptyResult.Error) {
        AdaptyError error = ((AdaptyResult.Error) result).getError();
        // handle the error
    }
});

try {
    const profile = await adapty.getProfile();
    // check the access
    if (profile.accessLevels["YOUR_ACCESS_LEVEL"]?.isActive) {
        // grant access to premium features
    }
} catch (error) {
  // handle the error
}

try {
  final profile = await Adapty().getProfile();
  // проверьте доступ
  if (profile.accessLevels["YOUR_ACCESS_LEVEL"]?.isActive ?? false) {
      // предоставить доступ к премиум-функциям
  }
} on AdaptyError catch (adaptyError) {
  // обработайте ошибку
} catch (e) {
}

Adapty.GetProfile((profile, error) => {
  if (error != null) {
    // handle the error
    return;
  }

  // check the access
  if (profile.AccessLevels["YOUR_ACCESS_LEVEL"]?.IsActive ?? false) {
      // grant access to premium features
  }
});

Adapty.getProfile()
    .onSuccess { profile ->
        // check the access
        if (profile.accessLevels["YOUR_ACCESS_LEVEL"]?.isActive == true) {
            // grant access to premium features
        }
    }
    .onError { error ->
        // handle the error
    }

try {
  const profile = await adapty.getProfile();
  // проверяем доступ
  if (profile.accessLevels["YOUR_ACCESS_LEVEL"]?.isActive) {
      // открываем доступ к premium-функциям
  }
} catch (error) {
  // обрабатываем ошибку
}