|
| |
Basics
APIs are simple and straightforward. There are 4:
1. Redirecting users to the Ipaya user check
| Description | Every time somebody visits a pay page at your site and has no valid cookie, your server should redirect him to Ipaya so that the automatic authentication process can start. Here you can read how you should put together the URL where you redirect the user to. In the flowchart, you do this in step 1. |
| Specs |
| Element | Type | Description |
| URL | | must be http://www.ipaya.com/check_user/ |
| site | variable | must be the same value that you entered as "Technical Name" in your Page Publishing Settings |
| _done | variable | complete URL of the page that the user was trying to visit |
|
|
| Example | This is a typical URL you redirect to:- http://www.ipaya.com/check_user/?site=example_com&
_done=http%3A%2F%2Fexample.com%2Farticle1
|
| Caution |
- If somebody has no valid cookie, don't try to display something - do a simple http redirect. If you don't, the automatic authentication won't work correctly.
- It is crucial that all redirect you do are http redirects, not meta redirects. Meta redirects stay in most browsers' history, while http redirects do not. This is to ensure that the authentication process is completely transparent to the user, works with all browsers and the back navigation works as expected.
- URL: Don't forget the "www" in www.ipaya.com
- URL: Don't forget the "/" after check_user/
- The _done URL has to be urlencoded, or data will be lost during redirection. A urlencoded URL looks like this: http%3A%2F%2Fexample.com
|
|
2. Redirecting users to you to set a cookie
| Description | After Ipaya has verified that a user has a subscription, the user is automatically redirected back to your "set cookie" URL. Here you can read how Ipaya puts together this URL. In the flowchart, this is done in step 2. |
| Specs |
| Element | Type | Description |
| URL | | will be the URL that you entered as "set cookie" script URL in your page publishing settings |
| temp_anon_user | variable | means temporarily, anonymized user. It's a long random string consisting of 30 letters and numbers that refers to the subscriber. When you report all pagehits to us, you need to tell us this string again together with every url, or we don't know who is behind your pagehits. |
| _done | variable | complete URL of the page that the user was trying to visit. Is urlencoded. |
|
|
| Example | This is a typical URL we redirect to:- http://example.com/setcookie.php/?
temp_anon_user=w3n4emk4xcjdsrjsdowe4n4e034nff&
_done=http%3A%2F%2Fexample.com%2Farticle1
|
| Note | If somebody accesses your "set cookie" URL, you should:
- verify temp_anon_user. This verification is done by calling Ipaya's "check_temp_permit" function - read more about it in Spec 3.
- set the cookie and check if it has been set, then redirect to the _done URL
|
| Caution |
- The _done URL we pass along is urlencoded. If your scripting language automatically urldecodes variables, you can directly work with it - otherwise you will have to decode it first.
|
|
3a. Requesting "check_temp_permit"
| Description | You must verify everybody that reaches your "set cookie" script by requesting a short piece of info from Ipaya via http. Here you can read how you should put together the URL that you then connect to. In the flowchart, this is done during step 3. |
| Specs |
| Element | Type | Description |
| URL | | must be http://www.ipaya.com/check_temp_permit/ |
| site | variable | must be the same value that you entered as "Technical Name" in your Page Publishing Settings |
| pass | variable | must be the same value that you entered as your account password |
| temp_anon_user | variable | the exact string you received from us |
|
|
| Example | This is a typical URL to check a temp permit:- http://www.ipaya.com/check_temp_permit/?
site=example_com&pass=mypassword&
temp_anon_user=w3n4emk4xcjdsrjsdowe4n4e034nff
|
| Note |
- We plan to offer a https version of this functionality in the future
|
| Caution |
- URL: Don't forget the "www" in www.ipaya.com
- URL: Don't forget the "/" after check_temp_permit/
|
|
3b. Output of "check_temp_permit"
| Description | If you request temp_permit info for a certain temp_anon_user using the previous specs, the received output will look like what you can read here. |
| Specs |
| Line | Element | Description |
| 1 | error | is an empty line if everything is ok. Otherwise, an error description is written here and all other lines are omitted |
| 2 | permit_ok | reads "yes" if the permit is ok. If the permit is not ok, an error is displayed on line 1 |
| 3 | valid_from | starting date + time for this temp_permit.
Format is "2003-01-21 13:31:07" |
| 4 | valid_till | expiry date + time for this temp_permit |
| 5 | ipaya_time | current date + time on the ipaya server |
|
|
| Example | This is a typical output:- (empty line)
yes
2003-01-21 13:31:07
2003-01-22 13:31:07
2003-01-21 13:31:07
|
| Notes |
- You can test this functionality by entering a correct check_temp_permit URL into your browser. For the output, choose "view source" in your browser to see the individual lines.
- Permits are normally valid for 24 hours. The period can be shorter if a user is near the end of his subscription.
- If somebody accesses a page and his permit is not valid anymore, you need to redirect this user to Ipaya's "check_user" function to let him get a new temp_anon_user.
- We send you ipaya_time because there might be a difference between your system clock and Ipaya's. Ipaya time is EST, basically, but it could be a few seconds off. It's a good idea to record all pagehits "in Ipaya time" because that's the format you need them anyway to report them back to Ipaya. To record in Ipaya time, we suggest you have a global variable in your system for the time difference between your system clock and Ipaya, and you update this variable whenever you get output from Ipaya's check_temp_permit function.
|
|
4a. Requesting pagehit report
| Description | Every 12 hours, Ipaya connects to your server to copy your list of pagehits to the Ipaya database. Here you can read how Ipaya puts together the URL to connect to your server. |
| Specs |
| Element | Type | Description |
| URL | | will be the URL that you entered in the input field "Reporting script" in your page publishing settings |
| site | variable | will be the same value that you entered as "Technical Name" in your Page Publishing Settings |
| pass | variable | must be the same value that you entered as your account password |
|
|
| Example | This is a typical URL we connect to:- http://example.com/reporting.php?
site=example_com&pass=mypassword
|
| Note |
- We plan to offer a https version of this functionality in the future
|
|
4b. Output of pagehit report
| Description | If we connect to your reporting script, your output should look like what you can read here. |
| Specs |
| Line | Element | Description |
| 1 | error | must be an empty line if everything is ok. Otherwise, an error description should be written here and the other lines should be omitted. If there are no pagehits to report, we recommend you to output an error with the description "zero hits" |
| 2, 3, ... | Data | a line for every pagehit you have recorded since the last time your script got called. Consists of 3 elements, each delimited by " , " (a space followed by a comma followed by a space). See below. |
|
Data specs:
| Position | Element | Description |
| 1 | date + time | date and time when a certain subscriber visited a page on your server. Format must be "2003-01-21 13:31:07" |
| 2 | temp_anon_user | which user visited your page. Must be equal to what we sent you in the beginning |
| 3 | url | the url of the page visited by this subscriber. Max length 200 characters. |
|
|
| Example | This is a typical output (it consists of 3 lines, but your browser might break it up to more lines):- (empty line)
2003-01-21 13:31:08 , w3n4emk4xcjdsrjsdowe4n4e034nff , http://example.com/article1
2003-01-21 13:37:41 , w3n4emk4xcjdsrjsdowe4n4e034nff , http://example.com/article2
This is another possible output: |
| Notes |
- Make sure that the date + time you report is in "Ipaya time".
- If a subscriber has visited a URL more than once, please report it back only once, as we delete all duplicates anyway
- Each temp_anon_user has a limited life of 24 hours or less. If a reported time is not within the boundaries, it won't be accepted. Also, please don't fake entries - it's not allowed, we can spot it if you do it and might disable your account.
- You can test your script by entering this URL into your browser. For the output, choose "view source" in your browser to see the individual lines. However, don't do this on a productive system as your script might think that is has delivered the data and won't deliver it again when Ipaya connects to your server
- To test your script on a productive system, visit your Data import summary, where we add a short summary for every reporting run, telling you what Ipaya did with every pagehit you reported.
|
|
|
