SmsCoin Instructions

====== Различия ====== Здесь показаны различия между выбранной ревизией и текущей версией данной страницы.

--- ru:service1:start [2013/06/12 13:18]
admin создано
+++ ru:service1:start [2020/08/21 14:16] (текущий)
@@ Строка 1: / Строка 1: @@
 ====== Техническое описание "смс:ключ" ======
-С технической точки зрения, услуга **смс:ключ** является простым способом ограничить доступ пользователя к содержимому того или иного сетевого ресурса. Для обхода ограничения используются индивидуально генерируемые пароли доступа; каждый такой пароль может иметь время действия и/или лимит количества использований, на ваше усмотрение. Доступ вновь закрывается, когда выполнилось поставленное вами условие — либо истекло время, либо количество использований пароля. Обратите внимание также на то, что изменения настроек вашего **смс:ключа** скажется только на тех пользователях, которые получили пароль после внесения изменений.
+===== Общая информация =====
+Услуга **смс:ключ** является простым способом ограничить доступ пользователя к содержимому того или иного сетевого ресурса, доступ к которому возможен только после ввода кода (пароля). Для того чтобы получить требуемый код доступа, пользователь отправляет Premium SMS на короткий номер и получает пароль в ответном сообщении. Владелец сайта, на котором находится контент, может задать параметры, определяющие, сколько раз и в течение какого времени этот код может быть использован. Легкость установки и гибкость настройки делают **смс:ключ** предпочтительным решением для большинства сайтов.
 Характерными особенностями **смс:ключа** являются:
+  * легкость и быстрота установки: стандартная интеграция занимает 5-10 минут;
+  * простота адаптации к требованиям пользователя: возможно не только изменение внешнего вида, но и частичная или полная замена формы запроса, добавление пользовательских параметров.
-  * легкость и быстрота установки (стандартная интеграция занимает пять-десять минут);
+В [[http://smscoin.com/software/|Библиотеке готовых скриптов]] имеются многочисленные варианты применения данной услуги. Также по ходу этой статьи встречаются ссылки, демонстрирующие различые аспекты ее реализации.
-  * простота адаптации к требованиям пользователя (возможно не только изменение внешнего вида, но и частичная/полная замена формы запроса без потери функциональности).
-Для установки услуги смс:ключ скопируйте его код в Панели управления и вставьте его в самом начале страницы, содержимое которой Вы планируете скрыть. Все, что находится ниже этого кода, будет доступно пользователю только после отправки сообщения и активации пароля, полученного в ответном SMS.
+===== Алгоритм работы =====
-====== Технология Flash ======
+  - Сетевой ресурс с ограниченным доступом предлагает пользователю ввести код доступа (пароль) или заполнить поля выбора страны/оператора для получения инструкции по отправке SMS ((Внешний вид формы может отличаться в зависимости от реализации)), которая включает в себя:
+    * короткий номер, на который необходимо отправить SMS;
+    * текст SMS, состоящий из:
+      * префикса;
+      * идентификатора **смс:ключа** (ID смс:ключа);
+      * необязательных дополнительных данных (см. [[#Смс:ключ с удаленным обработчиком|смс:ключ с удаленным обработчиком]]).
+    * стоимость SMS, которая в зависимости от страны может как включать, так и не включать НДС;
+    * указание о дополнительных налогах и сборах, которые могут быть установлены в выбранной стране;
+    * дополнительная информация: правила составления текста SMS, условия ответственности, информация о технической поддержке и пр.
+  - Отправленное пользователем SMS-сообщение через оператора поступает на наш сервер.
+  - Согласно тексту SMS определяется соответствующий **смс:ключ** и проверяется:
+    * статус оплаты принятого оператором сотовой связи сообщения;
+    * соответствие стоимости принятого SMS-сообщения и стоимости, установленной в настройках **смс:ключа**
+  - Если проверка прошла успешно, на нашем сервере генерируется и фиксируется в базе данных уникальный, в пределах данного **смс:ключа**, код доступа. При этом также фиксируются следующие параметры:
+    * Access limit - количество раз, которое можно использовать код, установленное в настройках **смс:ключа** на момент генерации кода;
+    * Accessed left - равное Access limit;
+    * Timeout - срок действия кода в минутах с момента его первого использования (ввода на сайт), установленный в настройках **смс:ключа** на момент генерации кода;
+    * Created - дата и время генерации кода доступа.
+  - Сгенерированный код передается оператору сотовой связи, который передает его пользователю в виде ответного сообщения.
+  - Если используется [[#Смс:ключ с удаленным обработчиком|смс:ключ с удаленным обработчиком]], то наш сервер с помощью HTTP-запроса вызывает обработчик по URL-адресу, указанному в настройках **смс:ключа** в поле **Result URL**, и передает ему необходимые [[#Данные, передаваемые на обработчик|данные]], включая сгенерированный код.
+  - Пользователь на сайте вводит код доступа, полученный в ответном SMS.
+  - Введенный код проверяется на корректность. При этом:
+    * в случае использования [[#Стандартная версия смс:ключа|стандартной версии смс:ключа]] (без удаленного обработчика) проверка осуществляется на сервере smscoin;
+    * в случае использования [[#Смс:ключ с удаленным обработчиком|смс:ключа с удаленным обработчиком]] проверка осуществляется на сервере сетевого ресурса.
+  - Если проверка прошла успешно, пользователю предоставляется доступ к оплаченному ресурсу.
+  - Код доступа прекращает свое действие, если было выполнено хотя-бы одно из условий ((В случае использования [[#Смс:ключ с удаленным обработчиком|смс:ключа с удаленным обработчиком]], владелец сервиса может изменить/добавить свои условия)):
+    * либо исчерпано количество раз, которое можно использовать код;
+    * либо истек срок действия кода.
-Несмотря на то, что мы не предоставляем отдельной версии смс:ключа для использования на сайтах, построенных целиком на технологии Flash, вы можете использовать приведенный ниже ActionScript-код для проверки паролей ключей:
+__**Примечание.**__ Генерируемый код доступа содержит в себе только цифры и буквы латинского алфавита. Соответственно, пользователь должен вводить только латинские буквы и цифры, даже если им соответствуют похожие по написанию буквы других алфавитов.
-<file>
+===== Добавление услуги и настройка =====
-var key : String = new String("идентификатор ключа");
-var pair : String = new String("пользовательский пароль");
-var loadVars : LoadVars = new LoadVars();
-loadVars.onLoad = function(success : Boolean) {
-    if(success && loadVars.toString() == "true") {
-        // пароль подтвержден
-    } else {
-        // пароль не подтвержден
-    }
-}
-loadVars.load("http://key.smscoin.com/key/?s_key=" + key
-    + "&s_pair=" + pair);
-</file>
-Обратите внимание: слова **идентификатор ключа** нужно заменить на идентификатор, присвоенный вашему смс:ключу , **пользовательский пароль** — на переданный пользователем пароль, а после комментарев **пароль подтвержден** и **пароль не подтвержден** должны идти соответствующие обработчики ситуаций — переход к закрытой части сайта или сообщение об ошибке (например, предложение ввести пароль повторно).
+Добавление/настройка услуги **смс:ключ** производится в Панели Управления -> Услуги -> смс:ключ. После добавления услуги необходимо на сетевом ресурсе разместить клиентский код скрипта, взаимодействующий с нашим сервером и реализующий соответствующую логику.
-====== Модификации кода ======
+Чтобы подключить к аккаунту новый **смс:ключ**, необходимо нажать "Добавить" и заполнить предлагаемую форму. При настройке параметров **смс:ключа** следует учитывать следующие особенности:
+  - **Адрес сайта**\\ Обязательно необходимо указать правильный адрес сайта, на котором планируется установить услугу. Этот адрес будет проверен модератором, после чего сервис заработает.
+  - **Стоимость**\\ Выбирается тариф (по стране/оператору) равный или больший заданной стоимости. Если стоимость выше любого тарифа в одной или нескольких странах (операторах), то они исключаются из списка доступных (из [[#Тарифная сетка|тарифной сетки]]). Если стоимость превышает тарифы во всех странах, то выдается пустой список (пустая [[#Тарифная сетка|тарифная сетка]]).
+  - **Время действия** и **Количество запросов**
+    * Если "Время действия" установлено в 0, то действие кода доступа будет неограниченно по времени.
+    * Если "Количество запросов" установлено в 0, действие кода будет неограниченно по количеству раз использования.
+    * Для получения безлимитного ("вечного") кода доступа необходимо оба параметра установить в 0.
+  - **Тип ключа**\\ Параметр необходимо задать, если ключ будет установлен на ресурсе, содержащим контент "для взрослых". В этом случае страны, в которых запрещено подключение сайтов "для взрослых", автоматически исключаются из списка доступных (из [[#Тарифная сетка|тарифной сетки]]), кроме России.
+  - **Передача паролей**\\ Задает режим работы **смс:ключа**. Существуют два режима работы:
+    * если не выбрано - используется [[#Стандартная версия смс:ключа|стандартная версия]];
+    * если выбрано - используется версия [[#Смс:ключ с удаленным обработчиком|с удаленным размещением обработчика]].
+  - **Адрес обработчика.**\\ Если включена **Передача паролей**, то необходимо задать URL-адрес обработчика, начинающийся с <nowiki>http://</nowiki>, на который нашим сервером передаются [[#Данные, передаваемые на обработчик|данные]] согласно [[#Реализация услуги смс:ключ с удаленным обработчиком|реализации услуги смс:ключ с удаленным обработчиком]].
+  - **пароль.**\\ Если включена **Передача паролей**, то необходимо задать пароль для защиты данных, передаваемых на удаленный обработчик. Задается произвольным набором символов в кодировке UTF-8 длиной, не превышающей 32 символа.
+  - **Рассылки**\\ Этот параметр не задействован, т.е. игнорируется.
+**Обратите внимание!** Изменение настроек **смс:ключа** скажется только на тех пользователях, которые получат код доступа только после сохраненных изменений.
-====== Установка языка по умолчанию ======
+===== Стандартная версия смс:ключа =====
+Эта услуга подходит для тех, кто не обладает навыками программирования или не уверен в своих возможностях. Код клиентского скрипта для использования стандартной версии **смс:ключа** доступен в Панели Управления по ссылке [[agregator:smscoin:smskey#PHP-версия скрипта по умолчанию|код ключа]]
+  http://smscoin.com/keys/html/<идентификатор ключа>/
+и имеет версии для наиболее распространенных языков программирования:
+  * PHP
+  * Perl
+  * Phyton
+  * ASP.NET
- По умолчанию все наши сервисы используют русский язык; в том случае, если часть Ваших пользователей не является русскоязычной, или Вы по каким-то другим причинам решили сменить используемый язык сервиса, просто измените адрес запроса в приведенном выше коде
+__**Замечание.**__
-<file>
+Несмотря на то, что мы не предоставляем отдельной версии **смс:ключа** для использования на сайтах, построенных целиком на технологии Flash, также имеется [[#Версия скрипта на технологии Flash|версия скрипта на технологии Flash]] для проверки паролей ключей.
-с
-http://key.smscoin.com/key/
+Для установки стандартной версии **смс:ключа** необходимо скопировать клиентский код скрипта из Панели Управления и вставить его в самом начале страницы (без пробелов и пустых строк!), содержимое которой планируется скрыть. Все, что находится ниже этого кода, будет доступно пользователю только после отправки SMS-сообщения и активации пароля, полученного в ответном SMS.\\
-на
+Посмотреть на пример работы стандартной версии **смс:ключа** можно [[http://smscoin.com/demo/key/normal/|здесь]]. В случае, если в настройках сервиса вы указали, что ресурс "для взрослых", результат будет несколько отличаться, как показано [[http://smscoin.com/demo/key/adult/|здесь]].
-http://key.smscoin.com/language/english/key/
+==== PHP-версия скрипта по умолчанию ====
+<code>
+<?php
+### SMS:Key v1.0.6 ###
+$old_ua = @ini_set('user_agent', 'smscoin_key_1.0.6');
+$key_id = <ID услуги смс:ключ>;
+$response = @file("http://key.smscoin.com/key/?s_key=".$key_id
+."&s_pair=".urlencode(substr($_GET["s_pair"],0,10))
+."&s_language=".urlencode(substr($_GET["s_language"],0,10))
+."&s_ip=".$_SERVER["REMOTE_ADDR"]
+."&s_url=".$_SERVER["SERVER_NAME"].htmlentities(urlencode($_SERVER["REQUEST_URI"])));
+if ($response !== false) {
+ if (count($response)>1 || $response[0] != 'true') {
+  die(implode("", $response));
+ }
+} else die('Не удалось запросить внешний сервер');
+@ini_set('user_agent', $old_ua);
+### SMS:Key end ###
+?>
+</code>
+**Исправление кодировки**\\
+Для исправления кодировки может понадобиться перед строкой
+<code>
+die(implode("", $response));
+</code>
+добавить следующую строку:
+<code>
+header('Content-Type: text/html; charset=utf-8');
+</code>
-(вместо english можно указать любой поддерживаемый язык).
+**Установка языка интерфейса по умолчанию**\\
-</file>
+По умолчанию используется русский язык интерфейса. Для смены языка необходимо заменить адрес запроса в приведенном ниже коде
+  http://key.smscoin.com/key/
+на
+  http://key.smscoin.com/language/english/key/
-====== Для мобильных браузеров ======
+Вместо english можно указать любой поддерживаемый язык.
+Пример работы можно увидеть [[http://smscoin.com/demo/key/english/|здесь]].
-**смс:ключ** теперь доступен также и посетителям WAP-сайтов - для того, чтобы вместо HTML генерировалась WML-разметка, Вам нужно только изменить в приведенном выше коде адрес запроса
+**Порядок взаимодействия скрипта с нашей системой**
+  - Скрипт выполняет GET-запрос на наш сервер по адресу http://key.smscoin.com/key/.\\ При этом, передаются следующие параметры:
+    * s_key - ID услуги смс:ключ;
+    * s_pair - код доступа (если введен пользователем);
+    * s_language - язык, на котором отображается страница оплаты;
+    * s_ip - IP адрес, с которого выполняется запрос (используется для автоматического определения страны и пр.);
+    * s_url - строка URL-запроса (используется для передачи пользовательских параметров обратно на страницу).\\ Кроме того, дополнительно можно передать следующие параметры:
+    * s_country - выбранная страна по-умолчанию;
+    * s_provider - выбранный оператор по-умолчанию;
+    * s_pure=1 - если код используется как часть пользовательской HTML-страницы (т.е. страница оплаты не будет иметь стандартное оформление).\\ В этом случае можно указать вспомогательный параметр:
+    * s_enc - кодировка пользовательской HTML-страницы.
+  - Согласно переданному **s_key** наш сервер осуществляет поиск записи, содержащей **s_pair**.
+  - Для найденного кода доступа (s_pair) проверяется:
+    * истекло ли время действия кода, прошедшее с момента его первого ввода (Accessed + Timeout);
+    * исчерпано ли количество раз использования кода (Accessed left > 0).
+  - Если проверка прошла успешно, то в соответствующей коду доступа записи в базе данных фиксируется следующая информация:
+    * Accessed - дата и время первого использования кода;
+    * IP - из параметра **s_ip**;
+    * URL - из параметра **s_url**;
+    * Accessed left - предыдущее значение, уменьшенное на единицу.
+  - Ответом на GET-запрос является массив **$response**, содержащий:
+    * единственный элемент **$response[0]='true'** - если код доступа корректный;
+    * стандартную форму ввода кода доступа (как правило) - в противном случае.
+  - Если введенный код доступа некорректный, то скрипт выводит на экран соответствующую стандартную форму и принудительно завершает выполнение файла, содержащего скрипт. В противном случае, выполняется код, расположенный ниже скрипта.
-<file>
+==== Альтернативная PHP-версия скрипта по умолчанию ====
-с
+Некоторые хостинги отключают возможность отправки GET-запроса удаленному скрипту при помощи функции file() (директива allow_url_fopen отключена). Специально для таких случаев существует альтернативная версия скрипта, приведенная ниже
+<code>
+<?php
+### sms:key v1.0.6 Extended ###
+$key_id = идентификатор ключа;
+$response = do_key_check("http://key.smscoin.com/key/?s_key=".$key_id
+."&s_pair=".urlencode(substr($_GET["s_pair"],0,10))
+."&s_language=".urlencode(substr($_GET["s_language"],0,10))
+."&s_ip=".$_SERVER["REMOTE_ADDR"]
+."&s_url=".$_SERVER["SERVER_NAME"].htmlentities(urlencode($_SERVER["REQUEST_URI"])));
+if (substr($response, 0, 4)  != 'true') {
+	die($response);
+}
+### sms:key end ###
+function do_key_check ($url = '') {
+	if (ini_get('allow_url_fopen') == 1) {
+		$old_ua = @ini_set('user_agent', 'smscoin_key_1.0.6');
+		$response = file($url);
+		@ini_set('user_agent', $old_ua);
+		if ($response !== false) {
+			return(implode("", $response));
+		} else {
+			return('Не удалось запросить внешний сервер (1)');
+		}
+	} elseif (function_exists('curl_init')) {
+		$ch = curl_init();
+		curl_setopt($ch, CURLOPT_URL, $url);
+		curl_setopt($ch, CURLOPT_BINARYTRANSFER, 1);
+		curl_setopt($ch, CURLOPT_HEADER, 0);
+		curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
+		curl_setopt($ch, CURLOPT_USERAGENT, 'smscoin_key_1.0.6_ex');
+		$response = curl_exec ($ch);
+		if (curl_error($ch) == '') {
+			return($response);
+		} else {
+			return('Не удалось запросить внешний сервер (2)');
+		}
+		curl_close($ch);
+	}
+	return('Не удалось запросить внешний сервер (3)');
+}
+?>
+</code>
+Этот код находится [[http://smscoin.com/mediabank/examples/smskey_extended_php.zip|здесь]].
- http://key.smscoin.com/key/
+==== PHP-версия скрипта для внедрения в дизайн страницы ====
-на
+Недостатком [[#PHP-версия скрипта по умолчанию|версии скрипта по умолчанию]] является недостаточная интеграция с дизайном сайта, на котором она используется. Существуют несколько вариантов решения этой проблемы.
-http://key.smscoin.com/key_wml/
+=== Вариант 1 ===
-</file>
+Заключается в том, чтобы заменить строку
+<code>
+die(implode("", $response));
+</code>
+на следующий код:
+<code>
+die('
+<!--
+ВЕРХНЯЯ ЧАСТЬ ОФОРМЛЕНИЯ
+-->
+<form action="http://'.$_SERVER["SERVER_NAME"]
+.$_SERVER["REQUEST_URI"].'" method="get">
+<!--
+ДОПОЛНИТЕЛЬНОЕ ОФОРМЛЕНИЕ И ПОЛЯ
+-->
+<input name="s_pair" type="text" value="" />
+<input type="submit" value="Открыть" /></form>
+<!--
+НИЖНЯЯ ЧАСТЬ ОФОРМЛЕНИЯ
+-->
+');
+</code>
+Отличительными особенностями данной модификации скрипта являются:
+  * оформление страницы целиком ложится на плечи владельца сетевого ресурса, включая вывод инструкции по отправке SMS (чтобы вывести эту инструкцию, потребуется [[#Тарифная сетка|тарифная сетка]] используемого смс:ключа),
+  * можно добавить любые дополнительные пользовательские параметры, которые могут быть использованы ниже в коде скрипта **смс:ключа**.
-====== Версия без оформления ======
+=== Вариант 2 ===
+Можно модифицировать стандартный скрипт следующим образом:
+<code>
+<?php
+// ****************** ВЕРХНЯЯ ЧАСТЬ ОФОРМЛЕНИЯ ******************
+### SMS:Key v1.0.6 ###
+$old_ua = @ini_set('user_agent', 'smscoin_key_1.0.6');
+$key_id = <ID услуги смс:ключ>;
+$response = @file("http://key.smscoin.com/key/?s_pure=1&s_key=".$key_id
+."&s_pair=".urlencode(substr($_GET["s_pair"],0,10))
+."&s_language=".urlencode(substr($_GET["s_language"],0,10))
+."&s_ip=".$_SERVER["REMOTE_ADDR"]
+."&s_url=".$_SERVER["SERVER_NAME"].htmlentities(urlencode($_SERVER["REQUEST_URI"])));
+if ($response !== false) {
+ if (count($response)>1 || $response[0] != 'true') {
+  echo implode("", $response);
+ } else{
+// ****************** ЗАКРЫТАЯ КЛЮЧОМ ИНФОРМАЦИЯ ******************
+ }
+} else die('Не удалось запросить внешний сервер');
+@ini_set('user_agent', $old_ua);
+### SMS:Key end ###
+// ****************** НИЖНЯЯ ЧАСТЬ ОФОРМЛЕНИЯ ******************
+?>
+</code>
+Отличительными особенностями данной модификации скрипта являются:
+  * использование параметра **s_pure=1** (пример работы параметра можно увидеть [[http://smscoin.com/demo/key/noskin/|здесь]].);
+  * возможность задать кодировку через параметр **s_enc** (кодировкой по умолчанию является windows-1251);
+  * возможность использовать оформление верхней и нижней части страницы;
+  * возможность использования CSS для оформления внешнего вида формы (CSS, используемую по умолчанию, можно скачать [[http://smscoin.com/skin/default/style.css|здесь]]);
+  * в случае некорректного кода доступа выполнение файла не завершается принудительно.
- Данная модификация предназначена для более тесной интеграции со структурой и дизайном Вашего ресурса. Если скрипту передавать в качестве параметра s_pure=1 (key.smscoin.com/key/?s_pure=1), то в результате работы выводится только актуальная HTML-разметка формы запроса; внешний вид формы, таким образом, легко видоизменить при помощи CSS. Пример работы скрипта находится здесь. CSS, используемую по умолчанию, можно скачать здесь.
+==== Версия скрипта на технологии Flash ====
-Обратите внимание, что кодировкой по умолчанию для версии ключа без оформления является windows-1251. Задать кодировку можно при помощи параметра s_enc (например, ?s_enc=koi8-r).
+Несмотря на то, что мы не предоставляем отдельной версии **смс:ключа** для использования на сайтах, построенных на технологии Flash, ниже приведен ActionScript-код для проверки кодов доступа (паролей):
+<code>
+var key : String = new String("ID услуги смс:ключ");
+var pair : String = new String("код доступа");
+var loadVars : LoadVars = new LoadVars();
+loadVars.onLoad = function(success : Boolean) {
+    if(success && loadVars.toString() == "true") {
+        // код доступа подтвержден
+    } else {
+        // код доступа не подтвержден
+    }
+}
+loadVars.load("http://key.smscoin.com/key/?s_key=" + key
+    + "&s_pair=" + pair);
+</code>
+Где:
+  * ID услуги смс:ключ - идентификатор услуги смс:ключ;
+  * код доступа — код доступа, введенный пользователем;
+  * код доступа подтвержден - переход к закрытой части сайта;
+  * код доступа не подтвержден - сообщение об ошибке или предложение ввести код доступа повторно.
-====== Вывод своего интерфейса ======
+===== Смс:ключ с удаленным обработчиком =====
- Используя смс:ключ, вы можете не только видоизменять стандартную форму ввода, но и выводить полностью свою версию интерфейса. Для вывода формы ввода пароля замените строку die(implode("", $response)); на следующий код:
+В [[#Стандартная версия смс:ключа|стандартной версии смс:ключа]] всю работу по выдаче и проверке паролей выполняет наш сервер. При этом, услуга лишена некоторой гибкости. В версии же с удаленным обработчиком владелец сервиса получает дополнительные преимущества:
+  * все пароли хранятся и обрабатываются на стороне владельца сервиса;
+  * использование любых языков программирования;
+  * полная свобода управления внешним видом услуги;
+  * возможность изменения, в определенных пределах, принципа работы услуги;
+  * в отправляемом пользователем SMS-сообщении появляется возможность после идентификатора **смс:ключа** добавить произвольный текст, который будет передан на обработчик (см.[[#Данные, передаваемые на обработчик]]);
+  * владелец сервиса в меньшей степени зависим от разного рода атак на наши сервера, перебоев работы сети и т.д.
-<file>
+Минусами услуги являются:
-die('<form action="http://'.$_SERVER["SERVER_NAME"]
+  * повышенные требования к навыкам программирования и работы с базами данных у владельцев ресурса;
-.$_SERVER["REQUEST_URI"].'" method="get">
+  * задержка (до 1-2 минут) вызова обработчика.
-<input name="s_pair" type="text" value="" />
-<input type="submit" value="Открыть" /></form>');
+==== Реализация услуги смс:ключ с удаленным обработчиком ====
-</file>
-В эту форму вы можете по мере надобности добавлять любые необходимые параметры, и они в случае успешного ввода пользователем пароля будут переданы вашему коду, идущему после смс:ключа.
+  - Владелец сервиса берет на себя организацию ограничения доступа к платному ресурсу, включая оформление и вывод инструкции по отправке SMS.
+  - Согласно [[#Алгоритм работы|Алгоритму работы]] вызываемый обработчик **Result URL** принимает [[#Данные, передаваемые на обработчик|соответствующие данные]] и проверяет корректность принятой информации с помощью вычисления MD5-хэш строки, состоящей из соединенных через двойное двоеточие ("::") параметров **secret_code, key, pair, timeout, limit, content, country, cost_local, provider** (в указанном порядке), и сравнения полученного результата со строкой **sign_v4**.
+  - В случае успешной проверки принятая информация, как правило, фиксируется в базе данных владельца сервиса (здесь и далее - локальной базе данных).
+  - Введенный пользователем код доступа обрабатывается в соответствии с реализованной владельцем логикой (поиск кода в локальной базе данных, проверка лимитов и т.п.).
-Чтобы вывести инструкции по отправке смс, вам потребуется список тарифов вашего смс:ключа. Вы можете получить эти данные в формате XML по адресу вида
+__**Замечания.**__
+  - Одна локальная база данных может быть использована для нескольких услуг **смс:ключ** (разные ID).
+  - Обработчик **Result URL** обязательно должен возвращать HTTP статус 200 OK и слово "OK" в теле ответа, даже если принятая информация некорректна. Это связано с тем, что если запрос на обработчик возвращает статус отличный от 200, то наш сервер еще дважды, примерно с минутным интервалом, будет пытаться повторить запросы. Для минимизации нагрузки на наш сервер это нежелательно.
-<file>
+Пример исходного кода скрипта, реализующего функционал **смс:ключа** с удаленным обработчиком находится [[http://smscoin.com/mediabank/examples/smskey_remote_php.zip|здесь]].
-http://key.smscoin.com/xml2/key/идентификатор ключа/
-и в формате JSON (JavaScript) по адресу
+==== Данные, передаваемые на обработчик ====
-http://key.smscoin.com/json/key/идентификатор ключа/
+^  Параметр  ^  Тип  ^  Описание  ^
-</file>
+|country  |  char(2)  |Двухбуквенный код страны  |
+|provider  |  char(16)  |Оператор сотовой связи  |
+|key  |  int  |Идентификатор услуги смс:ключ  |
+|pair  |  char(10)  |Сгенерированный нашим сервером пароль  |
+|timeout  |  int  |Время жизни сгенерированного пароля (pair) в минутах  |
+|limit  |  int  |Количество активаций сгенерированного пароля  |
+|content  |  char(128)  |Текст сообщения, следующий за идентификатором услуги смс:ключ  |
+|cost_local  |  float  |Стоимость SMS-сообщения в локальной валюте  |
+|sign_v4  |  char(32)  |MD5-хэш строки, состоящей из соединенных через двойное двоеточие ("::") параметров\\ secret_code, key, pair, timeout, limit, content, country, cost_local, provider (в указанном порядке),\\ где secret_code - значение поля "пароль." в настройках услуги смс:ключ в Панели Управления  |
+|  Пользовательские данные  |||
+|user_1\\ user_2\\ ...\\ user_n  |    |Не обязательный перечень параметров, определяемый пользователем,\\ который задается в строке **Адреса обработчика** в Панели Управления в настройках услуги.\\ Суммарное ограничение размера всех пар "поле-значение" составляет 155 символов.\\ \\ __**Внимание!**__\\ Пользовательские параметры не должны начинаться с префикса s_,\\  поскольку его использование зарезервировано для наших внутренних нужд.  |
-Приведенные адреса содержат полностью идентичную информацию, разнится только ее представление.
-Данные содержат также информацию о номерах, на которые пользователи должны отправлять сообщения (поле number), и префиксах, необходимых для обработки сообщений нашей системой (поле prefix); в разных странах, соответственно, действуют разные номера и префиксы. Для того, чтобы сообщение было ассоциировано с Вашим сервисом, оно должно иметь вид
+==== Типичный PHP-скрипт удаленного обработчика ====
+<code>
+<?php
+// ПРЕДВАРИТЕЛЬНЫЙ КОД
+	// the function returns an MD5 of parameters passed
+	// функция возвращает MD5 переданных ей параметров
+	function ref_sign() {
+		$params = func_get_args();
+		$prehash = implode("::", $params);
+		return md5($prehash);
+	}
+	// filtering junk off acquired parameters
+	// парсим полученные параметры на предмет мусора
+	foreach($_GET as $k => $v) {
+		$_GET[$k] =  substr(trim(strip_tags($v)), 0, 250);
+	}
-**префикс идентификатор ключа**
+        // service secret code
+	// секретный код сервиса
+	$secret_code = KEY_SECRET;
-и быть отправлено на действующий в рамках страны номер, верный для выбранного Вами тарифа.
+	// collecting required data
+	// собираем необходимые данные
+	$key        = $_REQUEST["key"];
+	$pair       = $_REQUEST["pair"];
+	$timeout    = $_REQUEST["timeout"];
+	$limit      = $_REQUEST["limit"];
+	$content    = $_REQUEST["content"];
+	$country    = $_REQUEST["country"];
+	$provider   = $_REQUEST["provider"];
+	$cost_local = $_REQUEST["cost_local"];
+	$sign       = $_REQUEST["sign_v4"];
-Если какая-либо страна не фигурирует в упомянутой выше тарифной сетке, значит, в данной стране отсутствует выбранный Вами при настройке тариф и она таким образом исключена из обработки; сообщения, отправленные пользователями, проживающими на территории этой страны, будут проигнорированы.
+	// users data
+	// пользовательские данные
+	$user_1     = $_REQUEST["user_1"];
+	$user_2     = $_REQUEST["user_2"];
+          ...
+	$user_n     = $_REQUEST["user_n"];
-Более подробные инструкции по работе с тарифными сетками в форматах XML и JSON можно найти здесь.
+	// making the reference signature
+	// создаем эталонную подпись
+	$reference = ref_sign($secret_code, $key, $pair, $timeout, $limit, $content, $country, $cost_local, $provider);
-Имеет смысл отметить, что все приведенные выше модификации совместимы между собой, т.е. вы можете использовать альтернативный код ключа, указав при этом кодировку и т.д.
+	// validating the signature
+	// проверяем, верна ли подпись
+	if($sign == $reference) {
+		// success, proceeding
+		// обрабатываем полученные данные
+		echo 'OK';
+	} else {
+		// failure, reporting error
+		// неправильно составлен запрос
+		echo 'checksum failed';
+	}
+?>
+</code>
-====== Удаленное размещение обработчика ======
+===== Тарифная сетка =====
+Тарифную сетку для услуги **смс:ключ** можно получить по следующим адресам:
-В стандартной версии смс:ключа всю работу по выдаче и проверке паролей выполняет наш сервер. Учитывая популярность услуги смс:ключ, мы создали более гибкую ее версию для тех наших пользователей, которые хорошо знакомы с программированием для WEB. Преимущества смс:ключа с удаленным размещением перед стандартным таковы:
+в формате XML:
+  http://service.smscoin.com/xml2/key/идентификатор ключа/
+  или
+  http://key.smscoin.com/xml2/key/идентификатор ключа/
+в формате JSON:
+  http://service.smscoin.com/json/key/идентификатор ключа/
+  или
+  http://key.smscoin.com/json/key/идентификатор ключа/
-  * все пароли хранятся и обрабатываются на вашей стороне, что позволяет локально управлять сессиями пользователей;
-  * вы можете управлять как внешним видом, так и в определенных пределах принципом работы услуги;
-  * услуга максимально устойчива к разного рода атакам на наши сервера, перебоям работы сети и т. д.
-**
+===== Примеры работы и готовые скрипты =====
-Внимание: для использования этой версии ключа категорически необходимо понимание общих принципов работы скриптов, исполняемых на стороне сервера.**
+==== Примеры работы ====
+^  Ссылка  ^  Описание  ^
+|[[http://smscoin.com/demo/key/normal/]]  |Стандартная версия  |
+|[[http://smscoin.com/demo/key/noskin/]]  |Стандартная версия без оформления  |
+|[[http://smscoin.com/demo/key/adult/]]  |Стандартная версия с отметкой "для взрослых" |
+|[[http://smscoin.com/demo/key/english/]]  |Стандартная версия с заданным языком по-умолчанию  |
+|[[http://smscoin.com/demo/key/wml/]]  |Стандартная версия для мобильных броузеров  |
+|[[http://demo.sms-payment-scripts.com/]]  |Услуги, реализованные с помощью [[http://smscoin.com/software/|Библиотеки готовых скриптов]]  |
+|[[http://demo.sms-payment-scripts.com/smskey_remote/check_popup.php]]  |Стандартный смс:ключ с удаленным обработчиком (без всплывающего окна)  |
+|[[http://demo.sms-payment-scripts.com/smskey_remote/check.php]]  |cмс:ключ с удаленным обработчиком c отображением инструкции в списке по странам |
+|[[http://demo.sms-payment-scripts.com/smskey_remote/check_popup.html]]  |cмс:ключ с удаленным обработчиком c отображением инструкции во всплывающем окне  |
+==== Готовые скрипты ====
+^  Ссылка  ^  Описание  ^
+|[[http://smscoin.com/mediabank/examples/smskey_extended_php.zip]]  |Альтернативная PHP-версия стандартного скрипта  |
+|[[http://smscoin.com/skin/default/style.css]]  |CSS по-умолчанию  |
+|[[http://smscoin.com/mediabank/examples/smskey_remote_php.zip]]  |cмс:ключ с удаленным обработчиком  |
+|[[http://smscoin.com/mediabank/examples/smskey_remote_php_geo.zip]]|cмс:ключ с удаленным обработчиком с автоопределением страны по IP |

SmsCoin Instructions

Инструменты пользователя

Инструменты сайта

Инструменты страницы