====== Technical description of the service sms:key ====== ==== Service description ==== **sms:key** is an SMS-based service which grants access through password to any content on a website. To gain access, user sends a Premium SMS to a short code and in reply receives a text password (key) which is to be entered on the website. You decide how often and for how long the password can be used. Both simple installation process and flexible configuration make sms:key preferable solution for the vast majority of websites. ===== Functionality ===== **sms:key** service is suitable in following cases: * content sale; * access limitations to any field on the website page or website section; * paid registration or access to any form which needs to be filled out; * paid file archives; * voting and much more. ===== Installation and configuration ===== Go to Control Panel -> Services -> sms:key. Click Add to connect new sms:key to your account and fill out the form below. Be sure to enter correct website address which the service will be connected to. The service will start working after the inspection of the website by our moderators. **There are two main versions of sms:key service - the standard one and the one with the remote handler.** ===== Standard sms:key version ===== In case you don't possess programming skills or you're not confident in your programming abilities, use this specific version. The code of the version is available in control panel for websites written in any popular programming language. In the scripts library you can find ready solutions for the most popular CMS (content management systems). Detailed description of technical details for installation and configuration of the standard sms:key version is located on sms:key technical description page. ==== Remote sms:key version ==== Remote sms:key version setup requires a high level of programming skills and database knowledge which will allow you to take the advantages of additional sms:key features, such as connecting your own password database, and much more. The description of technical details for installation and configuration of remote sms:key version is located on remote sms:key technical description page . ====Technical description==== From technical point of view, sms:key is a way of restricting user's ability to visit certain web-resources. In order to allow a user to review the restricted content, individual access passwords are generated; each one of these passwords can have a time and/or visit count limit. Access to certain password is denied when the time is up OR when the visit count limit is hit, whatever comes first. Be careful while adjusting the options though: note that when you change your sms:key settings, it will be applicable only for those users who signed up after the change came into force. Unique characteristics of **sms:key** are: * the simplicity of installation (standard setup takes 5-10 minutes); * the easiness of adaptation to user's specific needs (it is possible not only to change the form appearance, but to replace the default form partially / totally with your own - without any functionality loss). ==== Flash technology ==== Despite the fact that we do not provide a separate sms:key version for use on sites built fully with Flash technology, you can use the following ActionScript code to check key passwords: var key : String = new String("key id"); var pair : String = new String("password supplied by user"); var loadVars : LoadVars = new LoadVars(); loadVars.onLoad = function(success : Boolean) { if(success && loadVars.toString() == "true") { // password accepted } else { // password declined } } loadVars.load("http://key.smscoin.com/key/?s_key=" + key + "&s_pair=" + pair); Note that you need to replace key id with your actual sms:key ID, to replace user password with the password supplied by the user, and following the password accepted and password declined comments, these situations should be handled accordingly - redirect to the restricted part of the site and informing of an error (for example, an offer to re-enter the password). ===== Code modifications ===== ====Default language setup==== Russian language is a default language in all of our services. In case when part of your users are not Russian speakers, or for some other reasons you decided to change the default language of the service, simply replace request address in the above code from http://key.smscoin.com/key/ to http://key.smscoin.com/language/english/key/ (instead of english you can specify any other supported language). ==== Version without styles ==== This modification is meant for closer integration with your resource structure and design. If parameter s_pure=1 (key.smscoin.com/key/?s_pure=1) is passed to the script, then the result will be that the actual HTML-layout request form will be displayed. This way, the external appearance of the form can be easily changed with the help of CSS. Click here to see an example. Click here to download default CSS. Please note that default encoding for sms:key version without styles is windows-1251. It is possible to set encoding with the help of s_enc parameter (for example, ?s_enc=koi8-r). **If allow_url_fopen option is disabled** Some hostings disable the ability to send GET-request to remote script with the help of file() function. For such cases an alternative key code is available in this archive. ==== Your own interface display ==== When using sms:key, you're not only able to change the standard form appearance, but to display your own interface version as well. For password input display form replace the die(implode("", $response)); line with the following code: die('
'); You can add necessary parameters here if needed, and if the password was entered correctly by the user, these parameters will be transferred to your code which follows sms:key. To display instructions for sending an SMS, you will need a list of your sms:key rates. You can obtain this data in XML format according to address http://key.smscoin.com/xml2/key/key id / and in JSON (JavaScript) format according to address http://key.smscoin.com/json/key/key id / These addresses contain the entire identical information, the only difference is the way it is presented. This data contains information about the short codes users have to send messages to (number field), and about keywords necessary to process the messages in system smscoin (prefix field). In each and every country different short codes and keywords are operating accordingly. In order for the message to be associated with your service, it should look like this: prefix key id and should be sent to the short code operating within specific country according to the rate scale chosen by you. If one of the countries doesn't appear in above-mentioned rate scale, that means the rate you have chosen during the setup process is unavailable within this specific country and that is why this country cannot be processed. Messages sent by the residents of this country will be ignored. Detailed instructions for working with rates scales in XML and JSON formats could be found here http://smscoin.net/info/tariffs-export/ It worth to mention that all the above-mentioned updates are compatible with each other that is you can use alternative key code while indicating the encoding etc. ===== Remote sms:key handler ===== In standard sms:key version our server is responsible for issuing and verifying the passwords. Given the popularity of sms:key services among our clients, we've created more flexible version of the above for those of you who have a good knowledge of WEB programming. The benefits of remote sms:key version as oppose to a standard one are: * All passwords are stored and processed on your side, thus allowing you to locally manage user sessions; * You can manage the appearance, as well as to some extent, functionality of the service; * The service is most resistant to all sorts of attacks on our servers, network disruptions, etc. **Note:** to be able to use the remote handler version of the key, one must understand the overall principle of how the scripts work on server side. ==== Implementation details ==== Message handler (Result URL) excepts the following parameters: ^ Параметр ^ Тип ^ Описание ^ | country | char(2) | Two letters country code | | provider | char(16) | Mobile carrier | | key | int | Your sms:key ID servic | | pair | char(10) | Password generated by your server | | timeout | int | The time limit of the generated password (pair) in minutes | | limit | int | The number of times the password was activated | | content | char(128) | Text message, following the ID of your service | | cost_local | float | SMS-message cost in local currency | | sign_v4 | char(32) | MD5-hash lines, consisting of combined through double colon ("::") parameters **secret_code, key, pair, timeout, limit, content, country, cost_local, provider** (in specified order), where **secret_code** - is the secret key for your sms:key service | ==== System requirements: ===== PHP >= 4.3 ==== Supported DBMS: ==== MySQL - requires MySQL module set up SQLite - equires SQLite module set up PDO:SQLite (object-oriented version) – requires PDO and SQlite modules set up (usually set on PHP >= 5.1) ==== Installation process: ==== 1. unpack the files \\ 2. change /lib/config.php \\ 3. set write permission to /lib/keys_db \\ 4. set write permission to /lib/local.xml \\ 5. run setup.php and uninstall it \\ 6. run cron.php \\ 7. customize your script according to example in check.php (can be uninstall afterwards) \\ 8. configure the key in control panel defining the full path to result.php and secret password as specified in configuration file. \\ ==== File Pack ===== /lib/config.php – configuration file which includes basic functions \\ /lib/keys_db – the base itself \\ /lib/local.xml XML file containing all rates there are \\ /check.php - sample containing the necessary code which displays and verifies passwords \\ /cron.php – file responsible for updating /lib/local.xml, can be run manually as well as using CRON \\ /result.php – file responsible for passwords reception from our server \\ /select.php – file to view the list of passwords, log-in and password to which specified in \\ /lib/config.php \\ /setup.php - creates the necessary tables in the database \\ ==== Implementation examples: ==== Check out the source code for the script [[http://smscoin.net/mediabank/examples/smskey_remote_php_en.zip |here]]. Code examples for generating payment instructions according to rate scale in XML and JSON formats can be downloaded [[http://smscoin.net/info/tariffs-export/ |here]]. Rate scale — an important element when working with this sms:key version. Scale is generated according to the settings of your specific service and always available in XML and JSON formats in addresses such as: http://key.smscoin.com/xml2/key/key id/ http://key.smscoin.com/json/key/key id/ XML-file above also contains information about short codes users send the messages to (number field), and keywords necessary for the processing of messages by our system (prefix field) which must be contained in the text of the message in order for our system to process it correctly. Within different countries various short codes are operating, and sometimes different keywords. To ensure that the message is identified with your service, it must look like this: keyword key ID arbitrary text and it should be sent to correct short code operating within the country of the sender and according to sms-message cost set by you. If a country does not appear in the rate scale mentioned earlier, it means that this specific country does not include the rate you chose during the set up process and thus won't be processed. Messages sent by users across the territory of this country, will be ignored. If a country does not appear in your service rate scale , it means that this specific country does not include the rate you chose during the set up process and thus messages sent by users across the territory of this country won't be processed. The entire list of parameters can be found in [[http://smscoin.net/info/tariffs-export/ | Rate scale]] page. ===== FAQ ===== ==== It is impossible to choose a country – the list is empty ==== Please check the .htaccess file, it might contain rules which cut the parameters transferred to the script. Make sure that the rate chosen in sms:key settings is available at least in one of the countries. Often times this kind of error happens due to settings option which is set to "always use maximum rate", but "not more than" field is set to $0. ==== Page encoding is incorrect. What should I do? ==== Before the line **die(implode(...))** in script code add the following line: \\ **header('Content-Type: text/html; charset=utf-8');** ==== Instead of password entry form I see a PHP code ==== Please make sure the file containing the key code ends with .php. Also, make sure that your hosting is supporting PHP (contact the hosting support team to find out).