Difference between revisions of "Resellers"

From Ace Stream Wiki
Jump to: navigation, search
(Новая страница: «==Термины== * '''Партнер''' - пользователь Ace Stream, который подтвердил свое согласие с условиями …»)
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
==Термины==
+
==Terms==
* '''Партнер''' - пользователь Ace Stream, который подтвердил свое согласие с условиями "Партнерского соглашения"
+
* '''Reseller''' – Ace Stream user who has got rights to sell paid Ace Stream options
* '''Клиент API''' - партнер, который имеет доступ к API
+
* '''User key''' - Ace Stream user's ID
* '''Ключ пользователя''' - идентификатор пользователя
+
* '''Option''' - additional service / software service of Ace Stream, which can be activated for a specific user key
* '''Услуга''' - дополнительная услуга, которая может быть активирована для конкретного ключа пользователя
+
* '''App''' - reseller's product (site, mobile or desktop application), which is used to sell options
* '''Реселлер''' - партнер, который продает услуги пользователям
 
* '''Приложение''' - продукт (как правило, сайт) реселлера, через который осуществляется продажа услуг
 
  
==Что такое ключ пользователя==
+
==How to become a reseller==
Ключ пользователя используется для идентификации пользователя в статистике, запросах API и т.п.
+
* log in to site https://accounts.acestream.net using your login (if you do not have the login, you have to [https://accounts.acestream.net/register register])
 +
* choose section [https://accounts.acestream.net/partnership "Partnership"] in a top menu
 +
* click button "Become a reseller"
  
Пользователю автоматически присвается новый ключ при регистрации на сайте Ace Stream.
+
==API for Resellers==
 +
API for resellers allows you to activate different additional options for users of your apps.
  
Реселлер может получить ключ пользователя с помощью протокола OAuth2.
+
A common scheme of work of API for resellers looks like this:
 +
* to activate a required option for a user your app (site, mobile or desktop app) sends a request to Ace Stream server, in which specifies user's id, option and activation period
 +
* the cost of specified option for the specified period is charged from your balance in Ace Stream system
 +
* specified option is activated for the user whose id you specified in the request
  
==Что такое API для реселлеров==
+
Full description of API for resellers you can find [[Reseller_API/en|here]].
API для реселлеров позволяет в автоматическом режиме активировать пользователям Ace Stream дополнительный услуги.
 
  
На данный момент API предоставляет такие функции:
+
To work with API you will need the following two identifiers:
* узнать стоимость услуги
+
* '''API key''' - string, used for reseller's ID in API requests
* активировать услугу для конкретного пользователя
+
* '''API secret''' - secret key, used for a digital signature of API requests
* получить список услуг, активных для конкретного пользователя в данный момент
 
  
Техническую спецификацию API можно посмотреть [[Reseller API|здесь]]
+
You can find these identifiers in section Reseller -> API settings in a left menu. The reseller can change a secret key by themselves (button "Edit API settings").
  
==Как получить доступ к API для реселлеров==
+
==Creating apps==
Когда пользователь Ace Stream становится партнером, он автоматически становится клиентом API и ему предоставляется доступ к API в виде двух идентификаторов:
+
To start working with API for resellers you have to create at least one app. To do this click button "Create a new application" in section Reseller -> Applications in the left menu. After this you will be proposed to fill fields "Name" (mandatory) and "Application's site"(optional).
* '''API key''' - строка, которая используется для идентификации партнера в запросах API
 
* '''API secret''' - секретный ключ, который используется для цифровой подписи запросов API
 
  
Секретный ключ партнер может поменять самостоятельно в админ-панели.
+
All your apps can be seen in section Reseller -> Applications in a table with the following fields:
 +
* Name - app's name that you specified when created the app
 +
* APP_ID - app's identifier (it is used in API requests)
 +
* Edit - edit the app (you can change app's name and site)
 +
* OAuth - edit settings OAuth of this app
 +
* API - open API-console of this app
  
==Как работает схема для реселлеров==
+
You will need OAuth settings only if you plan to identify users using OAuth2 technology (usually, it is necessary for sites' owners).
Предположим, что пользователь test@someservice.com решил стать партнером Ace Stream и продавать пользователям услугу "No ADs" (отключение рекламы Ace Stream).
 
  
Для этого пользователю необходимо:
+
API-console allows you to send requests on behalf of your application directly from site. The console is intended primarily to demonstrate the formation of requests to API (each request and response appear in text fields at the bottom of the page).
* зарегистрироваться на в системе Ace Stream
 
* стать партнером, подтвердив свое согласие с условиями "Партнерского соглашения"
 
* создать новое приложение (партнер может создать несколько приложений; каждое приложение имеет свое название, адрес сайта и идентификатор OAuth2)
 
  
Для того, чтобы продать услугу пользователю, реселлер должен отправить API-запрос с такими данными:
+
<span style="color: #a00;">Attention!</span> API-console is not an emulator of requests - all requests are real and are sent to production-servers. It means that when some paid option is activated from console money will be withdrawn from your balance. If you would like to work with API for resellers in a test mode, use [[Reseller_API_Sandbox|sandbox]].
 +
 
 +
==Options activation reminder==
 +
App engine can notice user about missing options. Notification method depends on API you choose:
 +
* more about Engine API  [[Engine_API#example-missing-option-on-start|here]]
 +
* more about HTTP API [[Engine_HTTP_API#stop-notifications|here]]
 +
 
 +
==Activation of options for users==
 +
To activate the option for user reseller has to call API method [[Reseller_API#activateService|activateService]] with the following data:
 
* API key
 
* API key
* OAuth2 Client ID
+
* APP_ID (application identifier)
* ключ пользователя
+
* user key
* идентификатор услуги
+
* option ID
* идентификатор периода, на который необходимо активировать услугу
+
* ID of period for which an option has to be activated
 +
 
 +
If the request was successful a certain amount of money will be charged from reseller's balance, and the option for the requested period will be activated.
 +
 
 +
If a specified option is already activated at this moment, then validation period of the option will continue for a stated period.
 +
 
 +
API Key and APP_ID you can find out on the site in section [https://accounts.acestream.net/reseller Reseller].
 +
 
 +
Identifiers of options and periods are described [[Reseller_API|here]]
 +
 
 +
As it is seen from the description, to activate options reseller has to know user key. This key can be obtained in two ways: either via OAuth2 protocol, or to create a new key using API for resellers. The first method is more suitable for sites' owners. The second - for apps' developers. Both methods are described below.
 +
 
 +
==Work scheme for sites' owners==
 +
Sites' owners can get user key using OAuth2 protocol. To do this they have to do the following steps:
 +
* reseller places on his site a button "Log in with Ace Stream"
 +
* after pressing this button everything goes according to OAuth2:
 +
** user is redirected to Ace Stream site
 +
** if he's not registered, he registers
 +
** if he's registered, but not logged in, he logs in
 +
** if user logs in to reseller's site via Ace Stream OAuth2 at the first time, he agrees to provide some of his personal data to reseller's site (email and user key)
 +
** user goes back to reseller's site
 +
** reseller's site receives email and user key according to OAuth2
 +
* now user is authorized at reseller's site, and the reseller has user key, by which he can activate the option for user
 +
 
 +
More detailed information about OAuth2 is [[OAuth2/en|here]].
  
При успешном выполнении запроса с баланса партнера будет списана определенная сумма, а у пользователя активируется услуга на указанный период.
+
==Work scheme for apps' developers==
 +
Apps' developers usually have access to [[Engine_Service_API/en|Engine service API]]. It gives them ability to upload user keys directly to Ace Stream Engine and activate options without direct user intervention.
  
Как видно из описания, для активации услуги реселлер должен знать ключ пользователя. Этот ключ реселлер может получить по протоколу OAuth2.
+
We propose the following work scheme:
Для этого:
+
* app checks  whether the required option is activated ([[Engine_Service_API#check_user_service|check_user_service]])
* реселлер на своем сайте размещает кнопку "Войти через Ace Stream", которая выполняет авторизацию пользователя по протоколу OAuth2
+
* if the option is not activated, app creates a new user key ([[Reseller_API#createUserKey|createUserKey]]) and uploads it to Ace Stream Engine ([[Engine_Service_API#load_extension|load_extension]])
* после нажатия на эту кнопку все проходит согласно OAuth2:
+
* app activates a required option for a new user key ([[Reseller_API#activateService|activateService]])
** пользователя перенаправляет на сайт Ace Stream
 
** если он не зарегистрирован, то регистрируется
 
** если зарегистрирован, но не залогинен, то выполняет процедуру входа
 
** если пользователь первый раз входит на сайт реселлера через Ace Stream OAuth2, то он дает свое согласие на предоставление некоторых персональных данных сайту реселлера (email и ключ пользователя)
 
** пользователь возвращается на сайт реселлера
 
** сайт реселлера получает email и ключ пользователя согласно OAuth2
 
  
* теперь пользователь авторизирован на сайте реселлера и у реселлера есть ключ пользователя, по которому он может активироватьему услугу
+
Described scheme assumes that reseller's app and Ace Stream Engine are run on the same device.

Revision as of 12:42, 6 September 2017

Terms

  • Reseller – Ace Stream user who has got rights to sell paid Ace Stream options
  • User key - Ace Stream user's ID
  • Option - additional service / software service of Ace Stream, which can be activated for a specific user key
  • App - reseller's product (site, mobile or desktop application), which is used to sell options

How to become a reseller

API for Resellers

API for resellers allows you to activate different additional options for users of your apps.

A common scheme of work of API for resellers looks like this:

  • to activate a required option for a user your app (site, mobile or desktop app) sends a request to Ace Stream server, in which specifies user's id, option and activation period
  • the cost of specified option for the specified period is charged from your balance in Ace Stream system
  • specified option is activated for the user whose id you specified in the request

Full description of API for resellers you can find here.

To work with API you will need the following two identifiers:

  • API key - string, used for reseller's ID in API requests
  • API secret - secret key, used for a digital signature of API requests

You can find these identifiers in section Reseller -> API settings in a left menu. The reseller can change a secret key by themselves (button "Edit API settings").

Creating apps

To start working with API for resellers you have to create at least one app. To do this click button "Create a new application" in section Reseller -> Applications in the left menu. After this you will be proposed to fill fields "Name" (mandatory) and "Application's site"(optional).

All your apps can be seen in section Reseller -> Applications in a table with the following fields:

  • Name - app's name that you specified when created the app
  • APP_ID - app's identifier (it is used in API requests)
  • Edit - edit the app (you can change app's name and site)
  • OAuth - edit settings OAuth of this app
  • API - open API-console of this app

You will need OAuth settings only if you plan to identify users using OAuth2 technology (usually, it is necessary for sites' owners).

API-console allows you to send requests on behalf of your application directly from site. The console is intended primarily to demonstrate the formation of requests to API (each request and response appear in text fields at the bottom of the page).

Attention! API-console is not an emulator of requests - all requests are real and are sent to production-servers. It means that when some paid option is activated from console money will be withdrawn from your balance. If you would like to work with API for resellers in a test mode, use sandbox.

Options activation reminder

App engine can notice user about missing options. Notification method depends on API you choose:

  • more about Engine API here
  • more about HTTP API here

Activation of options for users

To activate the option for user reseller has to call API method activateService with the following data:

  • API key
  • APP_ID (application identifier)
  • user key
  • option ID
  • ID of period for which an option has to be activated

If the request was successful a certain amount of money will be charged from reseller's balance, and the option for the requested period will be activated.

If a specified option is already activated at this moment, then validation period of the option will continue for a stated period.

API Key and APP_ID you can find out on the site in section Reseller.

Identifiers of options and periods are described here

As it is seen from the description, to activate options reseller has to know user key. This key can be obtained in two ways: either via OAuth2 protocol, or to create a new key using API for resellers. The first method is more suitable for sites' owners. The second - for apps' developers. Both methods are described below.

Work scheme for sites' owners

Sites' owners can get user key using OAuth2 protocol. To do this they have to do the following steps:

  • reseller places on his site a button "Log in with Ace Stream"
  • after pressing this button everything goes according to OAuth2:
    • user is redirected to Ace Stream site
    • if he's not registered, he registers
    • if he's registered, but not logged in, he logs in
    • if user logs in to reseller's site via Ace Stream OAuth2 at the first time, he agrees to provide some of his personal data to reseller's site (email and user key)
    • user goes back to reseller's site
    • reseller's site receives email and user key according to OAuth2
  • now user is authorized at reseller's site, and the reseller has user key, by which he can activate the option for user

More detailed information about OAuth2 is here.

Work scheme for apps' developers

Apps' developers usually have access to Engine service API. It gives them ability to upload user keys directly to Ace Stream Engine and activate options without direct user intervention.

We propose the following work scheme:

Described scheme assumes that reseller's app and Ace Stream Engine are run on the same device.