README.md in linkshare_api-0.2.0 vs README.md in linkshare_api-0.3.0
- old
+ new
@@ -1,18 +1,23 @@
# LinkShare API
[](http://badge.fury.io/rb/linkshare_api)
[](https://travis-ci.org/rmarescu/linkshare_api)
-Ruby wrapper for [LinkShare Publisher Web Services](http://helpcenter.linkshare.com/publisher/categories.php?categoryid=71).
+Ruby wrapper for [LinkShare Publisher Web Services](https://rakutenlinkshare.zendesk.com).
Supported web services:
-* [Automated LinkGenerator](#automated-link-generator)
+* [Deep Linking](#deep-linking) (previously [Automated LinkGenerator](#automated-link-generator))
* [Merchandiser Query Tool](#merchandiser-query-tool)
+* [Coupon Web Service](#coupon-web-service)
If you need services that are not yet supported, feel free to [contribute](#contributing).
For questions or bugs please [create an issue](../../issues/new).
+## <a id="requirement"></a>Requirements
+
+[Ruby](http://www.ruby-lang.org/en/downloads/) 1.9 or above.
+
## <a id="installation"></a>Installation
Add this line to your application's Gemfile:
gem 'linkshare_api'
@@ -23,36 +28,72 @@
Or install it yourself as:
$ gem install linkshare_api
-## <a id="requirement"></a>Requirements
+## <a id="configuration"></a>Configuration
-[Ruby](http://www.ruby-lang.org/en/downloads/) 1.9 or above.
+Before using **LinkShare API** you need to set up your publisher token first. If you use Ruby on Rails, the token can be set in a configuration file (i.e. `app/config/initializers/linkshare_api.rb`), otherwise just set it in your script. The token can be found on LinkShare's Web Services page under the Links tab.
-## <a id="usage"></a>Usage
+```ruby
+LinkshareAPI.token = ENV["LINKSHARE_TOKEN"]
+```
-Before using **LinkShare API** you need to set up your publisher token first. If you use Ruby on Rails, the token can be set in a configuration file (i.e. `app/config/initializers/linkshare_api.rb`), otherwise just set it in your script. The token can be found on LinkShare's Web Services page under the Links tab.
+Affiliate ID is required for using Deep Linking.
```ruby
-require "linkshare_api" # no need for RoR
+LinkshareAPI.affiliate_id = ENV["LINKSHARE_AFFILIATE_ID"]
+```
+
+By default linkshare_api logs to STDOUT. To use your own logger implementation you have to specify it using `LinkshareAPI.logger`
+
+### Configuration example
+
+Would apply for Ruby on Rails. Create `app/config/initializers/linkshare_api.rb` and add the following content:
+
+```ruby
LinkshareAPI.token = ENV["LINKSHARE_TOKEN"]
+LinkshareAPI.affiliate_id = ENV["LINKSHARE_AFFILIATE_ID"]
+LinkshareAPI.logger = Rails.logger
```
+## <a id="usage"></a>Usage
+
+### Deep Linking
+
+Generate affiliate URLs using [Deep Linking](https://rakutenlinkshare.zendesk.com/hc/en-us/articles/201295755-Guide-to-Deep-Linking) service.
+Below is an example of generating an affiliate URL for [Walmart](http://www.walmart.com). Walmart merchant code is `2149`.
+
+```ruby
+require "linkshare_api" # No need for RoR
+
+LinkshareAPI.affiliate_id = ENV["LINKSHARE_AFFILIATE_ID"] # must be set in order to use Deep Linking, otherwise will fall back to Automated Link Generator
+url = "http://www.walmart.com/cp/Electronics/3944?povid=P1171-C1093.2766-L33"
+affiliate_url = LinkshareAPI.link_generator(2149, url)
+# http://click.linksynergy.com/deeplink?id=your_affiliate_id&mid=2149&murl=http%3A%2F%2Fwww.walmart.com%2Fcp%2FElectronics%2F3944%3Fpovid%3DP1171-C1093.2766-L33
+```
+
+**Note:** The link is generated manually, therefore you must ensure that the Affiliate ID provided is valid.
+
### Automated Link Generator
-Generate affiliate URLs using [Automated LinkGenerator](http://helpcenter.linkshare.com/publisher/categories.php?categoryid=72) service.
+**Deprecation Notice**
+
+**As of October 2014, Automated LinkGenerator is discontinued in favor of Deep Linking.** To use [Deep Linking](#deep-linking) instead, you only have to set `LinkshareAPI.affiliate_id`. Everything else remains the same.
+
+Generate affiliate URLs using [Automated LinkGenerator](https://rakutenlinkshare.zendesk.com/hc/en-us/articles/201343135-Automated-LinkGenerator-Guidelines) service.
Below is an example of generating an affiliate URL for [Walmart](http://www.walmart.com). Walmart merchant code is `2149`.
```ruby
url = "http://www.walmart.com/cp/Electronics/3944?povid=P1171-C1093.2766-L33"
affiliate_url = LinkshareAPI.link_generator(2149, url)
+# http://linksynergy.walmart.com/fs-bin/click?id=your_affiliate_id&subid=0&offerid=223073.1&type=10&tmpid=273&RD_PARM1=http%3A%2F%2Fwww.walmart.com%2Fcp%2FElectronics%2F3944%3F&RD_PARM2=povid%3DP1171-C1093.2766-L33
```
### Merchandiser Query Tool
-Search for products using [Merchandiser Query Tool](http://helpcenter.linkshare.com/publisher/categories.php?categoryid=74) service.
+Search for products using [Merchandiser Query Tool](https://rakutenlinkshare.zendesk.com/hc/en-us/articles/201483905-Merchandiser-Query-Tool-API-Guidelines) service.
```ruby
response = LinkshareAPI.product_search(keyword: "laptop")
# Return the number of total records that match the search criteria
puts response.total_matches # -1 means more than 4000 results (see doc)
@@ -68,11 +109,11 @@
puts "Price: #{item.price.__content__} #{item.price.currency}"
puts "URL: #{item.linkurl}"
end
```
-`product_search` accepts a hash as argument, and can include all available options. For a complete list of options please visit http://helpcenter.linkshare.com/publisher/questions.php?questionid=652.
+`product_search` accepts a hash as argument, and can include all available options. For a complete list of options please visit https://rakutenlinkshare.zendesk.com/hc/en-us/articles/201483905-Merchandiser-Query-Tool-API-Guidelines.
```ruby
# Search "laptop" only for Wal-Mart, within Electronics category,
# sorted by price ascending, and limit to 10 items per page.
options = {
@@ -97,12 +138,12 @@
end
```
When using the `all` method, `response` object is updated with the data returned by the last API request (last page). `response.all` returns the `data` array.
-### Coupon Web Services
+### Coupon Web Service
-Easy access to coupons and promotional link data for your advertisers using [Coupon Web Service](http://helpcenter.linkshare.com/publisher/questions.php?questionid=865)
+Easy access to coupons and promotional link data for your advertisers using [Coupon Web Service](https://rakutenlinkshare.zendesk.com/hc/en-us/articles/200919909-Using-the-Coupon-Web-Service)
```ruby
# Search for promotion types "Clearance" (id 3) and "Dollar Amount Off" (id 5)
# from Wal-Mart (id 2149) within category "Apparel - Babies & Kids" (id 3)
# in the US network (id 1)