Content Partner’s Guide to
IsUserEntitled API
Version 3.4
July 22, 2010
www.motricity.com
1
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
CONTENTS
1
Introduction ......................................................................................................................... 3
2
Overview of IsUserEntitled API ............................................................................................... 3
2.1 Description ....................................................................................................................... 3
2.2 Request Sequence ............................................................................................................. 5
2.3 Subscriber Session Management ......................................................................................... 6
2.4 Functions ......................................................................................................................... 6
2.5 Input Parameters .............................................................................................................. 6
2.6 Partner Evidence Token Hash .............................................................................................. 7
2.7 Output Parameters ............................................................................................................ 9
3
Linking to Content from VZW Mobile Web Portal ..................................................................... 10
3.1 Providing User Profile Data to Content Partner Site .............................................................. 10
4
API Error Handling .............................................................................................................. 11
5
Implementation Process ...................................................................................................... 12
5.1 Content Management Process ........................................................................................... 12
5.2 Implementation Verification Criteria .................................................................................. 13
6
Troubleshooting Guide ........................................................................................................ 13
Contact Information ................................................................................................................ 16
7
Appendix ........................................................................................................................... 16
8
Document Control............................................................................................................... 20
www.motricity.com
2
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
1 Introduction
Audience
This document is intended for VZW Content Partners who will be providing premium content to
subscribers of mobile web devices.
Purpose of the API
The Application Programming Interface (API) called IsUserEntitled is an interface method which
ensures a VZW subscriber is authorized to access content application(s) of Content Partners.
Content Partners, and each of their applications, must be registered with Verizon Wireless to utilize
the API capabilities. A Deck Change Request (DCR) form must be in place for each of the Content
Partner’s applications. See section 5 – Implementation Process for details.
How to Use This Document
To provide you an understanding of the API and how to it can be used to deliver premium content,
this document has been structured as follows:






Section 2 – Overview of IsUserEntitled API: Obtain an overview of the API, how it functions,
performs premium content authorization, and what are its detailed parameters to enable
integration with VZW’s Mobile Web portal.
Section 3 – Linking to Premium Content from VZW Mobile Web Portal: Understand how to use
the API in various scenarios and how its URL parameters can be used to personalize premium
content
Section 4 – Partner API Error Handling: Be familiar with the various IsUserEntitled responses
and the appropriate actions for each; including error handling
Section 5 – Implementation Process: Understand where Content Partner integration and
validation of the API fits in the implementation process of Premium Content.
Section 6 – Troubleshooting Guide: FAQs and Contact Information for API support
Section 7 – Appendix: Detailed information as reference for above sections.
2 Overview of IsUserEntitled API
The IsUserEntitled API is a method for ensuring a VZW subscriber is authorized to access Premium
Content. See Appendix A for a definition of Premium content and other available content types.
2.1 Description
When a Content Partner’s premium content is implemented on the Mobile Web (“the Portal”), an
authorization check, using the IsUserEntitled API, must be implemented by the Content Partner to
ensure that the subscriber traffic is authorized.
If the API validates that the subscriber is authorized, the subscriber will be directed to the premium
content site.
www.motricity.com
3
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
If the API cannot validate that the subscriber is authorized, the IsUserEntitled method returns the
url to the product’s subscription landing page. The content Partner’s implementation needs to
redirect unauthorized users to subscription landing page url returned in the API response.
www.motricity.com
4
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
2.2 Request Sequence
4
Response to Subscriber
1b
1a
Mobile Web
“Portal”
Content Partner
Partner Service
Locator (PSL)
Web Service
2
IsUserEntitled
API
Call to IsUserEntitled
(PartnerID, PartnerEvidence
UserID, UserEvidence,
ProductID, ProductVersion)
Premium
Content site
3
IsUserEntitled Response
(Yes | No - redirect to Subscription
Landing page)
Authorization Steps
2.2.1 Subscriber access to Premium Content site
The subscriber may choose a link from the Portal (1a), or the subscriber may directly
enter the URL of the Premium Content site (1b).
2.2.2 IsUserEntitled API
The Premium Content Partner calls the IsUserEntitled API (2) to validate that the
subscriber is entitled to access the Premium Content site.
2.2.3 API Authentication
The API validates that the Premium ContentPartner is valid, and the subscriber has
access to premium content. If both are valid, then the API responds to the Content
Partner that the subscriber is authorized (3). If the subscriber does not have access to
premium content, then the API responds with a negative response (3) along with the
subscription landing page URL to which the subscriber should be redirected.
2.2.4 Subscriber Entitled
The Content Partner provides content to Subscriber(4).
2.2.5
Subscriber not Entitled
The Content Partner redirects subscriber to subscription landing page. (4)
www.motricity.com
5
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
2.3 Subscriber Session Management
While a subscriber is accessing a Premium Content site, the Content Partner should ensure the
subscriber maintains a valid session. After the initial successful call to the IsUserEntitled API,
subsequent calls should be made (a) every 30-minutes or (b) any time the subscriber IP changes.
It is not necessary, nor is it desired, that the Content Partner call IsUserEntitled API for every
subscriber page view.
2.4 Functions
The URL locations for the IsUserEntitled API are:
PROD: https://premiumct.vzw.mcore.com/PartnerServices/PartnerServiceLocator.asmx
Please Note: In order to use plain text PartnerEvidence with IsUserEntitled API the call will need be
made over https, using SSL version 3 (SSL3), and at least 128-bit encryption.
Also explicitly set the location url in your proxy classes to
https://premiumct.vzw.mcore.com/PartnerServices/PartnerServiceLocator.asmx
The soap samples can be found at
https://premiumct.vzw.mcore.com/PartnerServices/PartnerServiceLocator.asmx?wsdl
(These samples can also be found in Appendix D.)
2.5 Input Parameters
This API makes use of the following parameters to ensure the VZW subscriber is appropriately
entitled. Please note encoding & other standards in Appendix C
IsUserEntitled Input - Validate subscriber’s entitlement Method. Using this method, an
authenticated Content Partner can validate a VZW subscriber’s entitlement to a service.
Parameter &
Sequence
Length/
Type
Description
Example
PartnerIdentity
Max
Length
320;
String
This is the Partner ID
[email protected]
PartnerEvidence
Variable
Length;
String
Via HTTP, a hash token
(constructed described below)
which includes the password
provided to the Content Partner.
-or –
Via SSL, clear-text partner
password. This is the same
password as is registered with the
Content Partner’s primary identity.
(Preferred option)
0322200519411000:435OEgjIh6nTW5i
KDHQDhA==
Subscriber’s XID – this is the value
in the subscriber’s HTTP header
from the subscriber request.
“HTTP_XID=” is the parameter you
0123456789ABCDEFGHIJKLMNOPQ
RSTUV@VzW
UserIdentity
Max
Length
320;
String
www.motricity.com
- or My_P@$$w0rd
6
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
IsUserEntitled Input - Validate subscriber’s entitlement Method. Using this method, an
authenticated Content Partner can validate a VZW subscriber’s entitlement to a service.
Parameter &
Sequence
Length/
Type
Description
Example
will look for in the HTTP HEADER
UserEvidence
Max
Length
320;
String
Subscriber’s source IP address this is the value in the subscriber’s
HTTP header from the subscriber’s
request. IPs are assigned
dynamically by Verizon Wireless.
This must be from a currently active
session.
69.78.188.155
“HTTP_USERIP=” is the parameter
to look for in the HTTP HEADER.
ProductID
Max
Length
128;
String
The Vendor Product Code that was
provided to the Content Partner by
Verizon Wireless in the DCR when
the Content Partner submitted this
product for the Mobile Web. No
special character restrictions.
MyProduct
ProductVersion
Max
Length 10;
String
The Vendor Product Version that
was provided to the Content Partner
by Verizon Wireless in the DCR
when the Content Partner submitted
this product for the Mobile Web. If
none was submitted, the value was
likely set to 1.0. No special
character restrictions.
1.0
2.6 Partner Evidence Token Hash
Partner evidence can take two forms: If the request to IsUserEntitled is made over Secure Socket Layer (SSL,
HTTPS), the PartnerEvidence is the partner clear-text password. SSL3 and at least 128-bit encryption strength
are required when using https for the request. If the request is not encrypted (HTTP), then the evidence token
hash must be used as follows.
The evidence token hash is an ASCII string with the following format:

DateTime + ‘:’ + Base64(MD5(DateTime + PartnerIdentity + Password))



DateTime
PartnerIdentity
Password
2.6.1
=
=
=
UTC Date/Time with form MMddyyyyHHmmssff
[email protected]
Clear-text password
Date/Time format
The DateTime is always UTC and should be formatted as ‘MMddyyyyHHmmssff’. A numeric value must be
padded with zeros in order to match its destination field length (‘08’ instead of ‘8’ for a two-digit field).
www.motricity.com
7
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
MM
dd
yyyy
HH
mm
ss
ff
two-digit month.
two-digit day of month.
four-digit year.
two-digit hour
two-digit minute
two-digit second
two-digit 1/100th‘s of a second
01-12.
01-31
2005+
00-23
00-59
00-59
00-99
Examples of this date format are as follows:
Midnight Jan 1st 2005:
1:23:45.67 Jan 23rd, 2005
0101200500000000
0123200501234567
2.6.2 Evidence String Construction
The Content Partner must use the same password to construct the PartnerEvidence Hash as is registered
with their Primary Identity.
The Content Partner constructs the signature in the following way:
 Get the DateTime as defined by the MMddyyyyHHmmssff format
 Concatenate in ‘x’ the DateTime + PartnerIdentity + Password
 Y = MD5(x)
 Z = Base64(Y)
 Take the resultant Z and prefix the clear text DateTime string with the ‘:’ as a delimiter.
2.6.3 Evidence Token Hash Examples
Below are examples of evidence Token Hash values for given input.
Partner Evidence Example #1
Evidence Field
Value
Partner Identity
[email protected]
Partner Password
P@55Word
Local Date/Time
2005-01-23 14:56:00.00 EST
Formatted UTC Date/Time string
0123200519560000
Hash string (before encoding)
[email protected]@55Word
Hash string (after encoding)
qhJ+fJrVnctM2Wv5MUXbBA==
Final Evidence string
0123200519560000: qhJ+fJrVnctM2Wv5MUXbBA==
Partner Evidence Example #2
Evidence Field
Value
Partner Identity
[email protected]
Partner Password
P@55Word
Local Date/Time
2005-12-30 00:00:00.00 PDT
Formatted UTC Date/Time string
1230200507000000
Hash string (before encoding)
[email protected]@55Word
www.motricity.com
8
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
Hash string (after encoding)
siEWsyA8XGZDnymEHrtEIQ==
Final Evidence string
1230200507000000: siEWsyA8XGZDnymEHrtEIQ==
Partner Evidence Example #3
Evidence Field
Value
Partner Identity
[email protected]
Partner Password
P@55Word
Local Date/Time
2005-11-22 00:44:55.99 CST
Formatted UTC Date/Time string
1122200506445599
Hash string (before encoding)
[email protected]@55Word
Hash string (after encoding)
bOrPL4653CBYp4wHUOJ5qw==
Final Evidence string
1122200506445599: bOrPL4653CBYp4wHUOJ5qw==
2.7 Output Parameters
Partner Web-Services return an XML SOAP ‘Result’ object. The ‘Result’ object, in turn, contains a ‘response’
node, which contains the entitlement and error data. See Appendix D for a full example of the XML SOAP
response.
If the returned error code is ‘0’ and the error description is ‘SUCCESS’, the submitted request was processed
successfully, with both user and partner evidence being validated correctly. In this case, the
‘UserEntitlementApproved’ value will indicate whether or not the subscriber has purchased the product (‘true’ or
‘false’).
If the returned error code is greater than ‘0’, there was a problem with the request. In this case the
‘UserEntitlementApproved’ value will always be ‘false’.
The API returns the following data:
 Returns landing page (object).
 Returns an error description of “SUCCESS” or error description text.
 Returns error integer of 0 with the description of “SUCCESS” or integer greater than 0 for error.
 The Premium Content Partner can choose to re-direct the subscriber if the UserEntitlementApproved
response is false.
Please note encoding & other standards in Appendix D.
IsUserEntitled Output- Validate subscriber’s entitlement method. Using this method, an authenticated
Content Partner can validate a subscriber’s entitlement to a service.
Parameter & Sequence
Length/Type
Description
Entitlement
Tag
Beginning & ending enclosure tags for
Boolean response object
UserEntitlementApproved
true or false
True for entitlement.
False for entitlement failed.
Error
Tag
Beginning & ending enclosure tags for error
information
www.motricity.com
9
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
IsUserEntitled Output- Validate subscriber’s entitlement method. Using this method, an authenticated
Content Partner can validate a subscriber’s entitlement to a service.
Parameter & Sequence
Length/Type
Description
ErrorDescription
ErrorCode
description- s:string
ErrorCode-Presently
4 digit integer s:int
LandingPages:string
ErrorDescription & Error code:
1. If entitlement processing works, (0)
SUCCESS is returned.
2. If a processing error occurs during
entitlement processing, an error code and
description are returned. (See Section 5.)
Landing Page:
The landing page will contain URL and
information submitted, (vendorId, productId,
productVersion, & Portal subscriber ID, should
their entitlement check return false with no
processing errors. At this point the Content
Partner has a choice of re-directing the
subscriber to sign up or just deny subscription.
LandingPage
3 Linking to Content from VZW Mobile Web Portal
There are options for how a link to a premium/non-premium content site can be set up on the VZW
Mobile Web portal:
Linking directly to Premium Content site
Entitlement of the VZW subscriber to a premium content site is checked on the VZW Portal
before redirecting the subscriber to the Content Partner site. This is the default setup for a VZW
premium content partner’s site and no further configuration is required. The Content Partner’s
site is still required to validate entitlement using the IsUserEntitled API as called out above.
Please work with VZW Partner Management to set up the premium content site in the Verizon
Developer Community site.
Linking to Non-Premium Content site
No entitlement check is performed on the VZW Portal before redirecting to a non-premium
content page on the VZW Content Partner site. It is up to the Content Partner to properly
implement the entitlement check on only the premium content portions of their site. Please
work with VZW Partner Management to set up the non-premium content site in the Verizon
Developer Community site.
3.1 Providing User Profile Data to Content Partner Site
The link to a VZW Content Partner site can optionally be configured to contain subscriber profile
data in the form of URL query parameters appended to the Content Partner site URL.
As described in the previous section, when VZW portal users choose to access a premium
content site, the appropriate entitlement to the content is verified. If access is granted, the
request will be redirected to the premium content site, optionally appending customization
information (i.e. portal user’s zip code) to the URL. Upon receipt of the redirected request, the
www.motricity.com
10
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
Premium Content Partner can extract the information from the URL and use it to customize the
response for the Portal user. For example, a portal user’s postal code can be used to limit the
scope of the premium content to a particular area that is more relevant to the portal user.
3.1.1
Configuring a Link to Contain User Profile Data
The customized parameters are requested in the Verizon Wireless Deck Change Request (DCR)
by the Premium Content Partner and approved by Verizon Wireless for that vendor product.
Currently, a VZW portal user’s zip code can be appended as a URL query parameter to the
Content Partner site URL. Please contact VZW Partner Management at
[email protected] if you’d like to get further details and/or implement
customized parameters.
3.1.2
Zip Code Parameters
The following table contains supported parameters that a Premium Content Partner can receive
via the redirected URL. By default, no customized parameters are appended to the URL. If a zip
code parameter is desired, please indicate this on the Verizon Wireless DCR.
Note: Any of the requested values can be returned as blank in the URL when no data is
available for the Portal user in question.
Output URL - http://vendor domain/url path?zip=98122
Parameter
Character &
Length
Description
Example
ZIP (if available)
Any character;
Maximum
Length is 50
Any Zip code
zip=98072
4 API Error Handling
The table below describes the different IsUserEntitled API responses and actions for each.
Expected Partner Action for given IsUserEntitled responses
User
Entitlement
Approved
Error Code
Expected Content Partner Action
True
0
Subscriber has purchased the premium content. Content
Partner shall allow access.
False
0
Subscriber has not purchased th premium content. Content
Partner shall redirect subscriber to the subscription landing
page (URL provided in IsUserEntitled response).
False
3008, 6004
There was problem with either application or user login.
Content Partner shall not allow access. See Section 6 –
Troubleshooting Guide.
www.motricity.com
11
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
Expected Partner Action for given IsUserEntitled responses
User
Entitlement
Approved
Error Code
Expected Content Partner Action
False
Other than 0,
3008, 6004
Content Partner shall not allow access. See error details in
Appendix E – Error Codes.
5 Implementation Process
5.1 Content Management Process
Verizon Wireless has established a process which enables Content Partner’s to provide premium
content sites to VZW subscribers. This process focuses on VZW Content Partner’s implementing
support of the IsUserEntitled API and VZW’s publication of premium content sites on the Mobile
Web portal. Content Partners should adhere to the following process:
Process Steps
Description
Existing VZW Content
Partner submits DCR
request to implement
Premium Content
Content Partner submits a completed DCR to Verizon Wireless.
Please contact VZW Partner Management at
[email protected] to obtain submission
requirements (i.e. submission dates to meet release dates).
VZW will process DCR and
Price Plan of Premium
Content
The DCR and Price Plan of the Content Partner’s premium content
shall be processed by VZW. The output of this process will be the
authentication credentials for the Content Partners. They include:




Partner ID
Password
Product ID
Version
VZW provides
Authentication Credentials
VZW shall submit authentication credentials to the Content
Partner(s).
Content Partner develops
and tests against
IsUserEntitled API
Content Partners are responsible for testing/validating that their
premium content sites are performing entitlement checks via the
IsUserEntitled API.
VZW schedules publication
of Content Partner’s
premium content
VZW will determine and communicate appropriate release date of
premium content to Content Partner.
Premium Content is added
to the VZW Portal and
Tested
The Content Partner’s premium content URLs shall be tested in
pre-production environments using various Verizon Wireless
devices.
Premium Content is
published to VZW
Production environment
During Content Release date, URL links to Content Partner’s
premium content sites are published to VZW’s production
environment and are made available to VZW subscribers.
www.motricity.com
12
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
Process Steps
Description
Post Release – Within 14
days of Premium Content
Release, Content Partner
validates entitlement
checks
The Content Partner is required to insure their site is providing
appropriate entitlement checks to new premium content; now
made available to VZW subscribers.
5.2 Implementation Verification Criteria
As part of Premium Partner integration, basic validation tests are performed to verify that
entitlement checks using IsUserEntitled API have been correctly implemented. Validation tests
include determining if the Premium Content Partner:
 Gives access to VZW subscribers who have a Premium subscription to the content.
 Does not give access to Portal users without a Premium subscription to the content
Failure to correctly implement the User entitlement process may result in the delay of the Premium
Partner content integration.
6 Troubleshooting Guide
Frequently Asked Questions
6.1 Why am I getting a ‘3008’ Login Error?
The 3008 error occurs when the supplied Partner Identity is not recognized. Please ensure you
Partner Identity string exactly matches that which was assigned to you. Ex:
[email protected]
If your Partner Identity exactly matches that which was supplied to you and you are still receiving
a 3008 error, please contact VZW Partner Management at [email protected]
6.2
Why am I getting a ‘6004’ Login Error?
The ‘6004’ Error code indicates either the application (Premium Content Partner) or the Portal user
login has failed. To distinguish between the two failures, you must look at the ‘ErrorDescription’
field.
If the error message begins with ‘AppLogin’, the application login is failing; See Why is my
application login failing? for more information.
If the error message starts with your Partner Identity (e.g. “[email protected]:email :
Cannot….”), the application login was successful and it is a user login issue. See Why is my Portal
user login failing? for more information.
6.3
Why is my application login failing?
If you are getting a 6004 error code and the error description indicates anything about ‘AppLogin’,
the Premium Partner login is failing. This is most likely occurring because the supplied
PartnerEvidence is invalid. The application login error description typically looks like:
AppLogin: Login failed.
The type of authentication you use will depend on the protocol used to make the IsUserEntitled
call. For unencrypted requests (HTTP), the Identity hash must be used. For secure requests
www.motricity.com
13
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
(HTTPS/SSL) clear text passwords must be used.
match your access scheme, login will fail.
6.4
If your application evidence type does not
Clear-text password
If you are using a clear text password, the call to IsUserEnttiled must be made over HTTPS (SSL).
If you are making a plain (HTTP) request, clear text password authentication will fail.
The password match is case sensitive. Please make sure your password matches exactly.
6.5
Identity Hash
Because of the multiple pieces of input data, multiple encoding steps, and the time sensitive nature
of the identity hash, failures can occur for several reasons. The below chart details the most
common scenarios:
Identity Hash
Description / Remedy
Problem
Incorrect Protocol
If your IsUserEntitled request uses HTTPS/SSL, the Identity hash
for evidence type
authentication will fail. If HTTPS/SSL is used, use your clear-text
password for partner identity.
Invalid Partner
Identity
Invalid Partner
Password
Incorrect date
string format
Incorrect date time
zone
Incorrect server
time
www.motricity.com
Be sure the Partner Identity (e.g. [email protected])
used to construct the Identity hash matches exactly that for the
PartnerIdentity parameter.
If the Partner identity parameters match and you receive a 6004
error, the problem lies elsewhere. If the PartnerIdentity
argument is invalid, you will receive a 3008 error.
Be sure the partner password used to construct the identity hash
matches exactly that which was supplied to you. The password is
case sensitive.
If you suspect your password is at fault, attempt as HTTP/SSH
connection which uses only the password in clear text. If you can
login using the same password via HTTP/SSL, the password is not
at fault. If you cannot, confirm you are entering our password
correctly then contact [email protected]
The format of the date string must match exactly. Make sure to
verify your date string is always using two-digit numbers for day,
month, hour, minute, second and hundredths of a second.
See the Date/Time format section for more details.
All date/time strings must be in GMT. If your date/time string is
generated in local time (or any other time), it will appear to be
expired.
See Date/Time format for more information on the date/time
string format.
See below for more information of password expiration.
The identity hash is only valid for a short time after which it is
generated. If the clock is off on the server which is generating
the IsUserEntitled requests, it will appear to the Motricity server
that the credentials are invalid and login will fail.
Be sure the clock(s) on your machine(s) are ‘close’ to the correct
time (within several seconds). It is recommended that you set up
the machine such that the clock will stay in sync automatically.
For quick reference, an accurate time reading may be obtained
from http://www.time.gov
14
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
6.6
Incorrect base64
or MD5 encoding
Both the MD5 and base64 encoding are done using the standard
encoding libraries.
With the MD5 being a one-way function it is impossible to tell
what the input was for a given evidence string. In order to verify
your encoding function we have provided examples to test against
in the Evidence token hash examples section.
Incorrect hash
string construction
Please ensure you are constructing the hash string according to
procedure laid out in Building the evidence string.
Why is my Portal Subscriber login failing?
If you are getting a 6004 error and the error message does not indicate an application login error,
it is likely the Portal user login failed.
In order for a Portal user to make a successful call IsUserEntitled call, they must have visited the
Verizon Portal. If a user directly enters a premium content URL or somehow navigates to the
Premium Content Partner site without first visiting the portal, they will not be allowed login access.
Partner identification and evidence is stripped out of the Portal user request header. Make sure
you are correctly reading the current XID and SIP values from the request headers. If you have
verified the correct XID and SIP are being stripped from the Portal user request header and you are
still seeing login issues, contact VZW Partner Management at
[email protected].
6.7
Why is UserEntitlementApproved always false?
The ‘UserEntitlementApproved’ value will only be true if these three factors are all in place:
a) Application login is successful
b) User login is successful
c) Portal user has purchased a subscription to the supplied product and version.
For (a) and (b), if there is a problem with login, it will be reflected in the ErrorCode and
ErrorDescription fields. If there is no error, the Portal user has not purchased the supplied product
and version.
If it’s determined that the Portal Subscriber does indeed have an active subscription to the product,
there are a few things to check. First, verify the name of the ProductID field. ProductID values are
usually a string, such as ‘MyProduct’. The ProductID, or Vendor Product ID, is a unique product
identifier assigned by the Content Partner to their application.
Please Note: ProductID is not the same as Vendor ID. The numeric Vendor ID is a unique value
assigned to you the Vendor by the VZW SCM system (e.g. ‘200000’ or ‘800000’).
6.8
What about HTTP GET and HTTP POST?
SOAP POST is the only supported method by which Premium Partners may access the Partner
Service Locator web service. HTTP GET and POST exist only for legacy support and for ease of
testing and should not be developed against.
www.motricity.com
15
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
Contact Information
For any Premium Content Partner support issues or questions, please contact Motricity at
[email protected]
When reporting errors please include as much information as is available, including:
Date and time the error occurred
IsUserEntitled input values (Partner and User Identity and Evidence, Product Info)
IsUserEntitled response, including error code and error description
Any other relevant context that might assist with troubleshooting.
7 Appendix
Appendix A – Definition of Content
There are two types of content which are available on Mobile Web. They are:
Non-Premium content – Content which VZW Mobile Web subscribers have unlimited access to and
does not require a paid content subscription.
Premium content – Content which can only be accessed if a subscriber has paid a required content
subscription. Premium content partners regulate subscription fees and content authorization.
Appendix B – Mobile Devices
Gateway, Non-Gateway, and RIM devices provide the VZW Mobile Web experience. Only VZW
gateway devices are able to display premium content.
Parameters
Gateway
NonRIM
Gateway
XID
X
UserIP
X
X
Source IP
X
Gateway devices receive input parameter ‘XID’ from the VZW gateway header. The other type of
devices (Non-Gateway and RIM) do not support XID
Example of VZW Gateway Devices:
LG VN250
Samsung U820
Example of VZW Non-Gateway Devices:
Droid
Droid Eris
Gateway devices which provide premium content are able to offer three different types of user
experiences. They are Mobile Web 2.0, Mobile Web Enhanced Authenticated, and Mobile Web 3.0.
www.motricity.com
16
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
Examples of all 3 User Experiences providing Premium Content:
Mobile Web 3.0
Mobile Web 2.0
Enhanced Authenticated
Appendix C – Sample IsUserEntitled API Soap
Soap In
POST /PartnerServiceLocator/PartnerServiceLocator.asmx HTTP/1.1
Host: 2k3s13906
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://www.InfoSpace.com/Partners/IsUserEntitled"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<IsUserEntitled xmlns="http://www.InfoSpace.com/Partners/">
<PartnerIdentity>string</PartnerIdentity>
<PartnerEvidence>string</PartnerEvidence>
www.motricity.com
17
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
<UserIdentity>string</UserIdentity>
<UserEvidence>string</UserEvidence>
<ProductID>string</ProductID>
<ProductVersion>string</ProductVersion>
</IsUserEntitled>
</soap:Body>
</soap:Envelope>
Soap Out (User not entitled)
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<IsUserEntitledResponse xmlns="http://www.InfoSpace.com/Partners/">
<Result>
<response xsi:type="EntitlementResult">
<Error>
<ErrorDescription>SUCCESS</ErrorDescription>
<ErrorCode>0</ErrorCode>
<LandingPage>http://www.verizon.com/entitlementfailed.htm?vendorID=777666&amp;productID
=123456&amp;productVersion=12312&amp;UID=6b740930-6300-406e-873c9b364a0876e4</LandingPage>
</Error>
<Entitlement>
<UserEntitlementApproved>false</UserEntitlementApproved>
</Entitlement>
</response>
</Result>
</IsUserEntitledResponse>
</soap:Body>
</soap:Envelope>
Appendix D – Error Codes
The following list contains the error values and text categories along with an explanation of the
error. Note that the actual error text will vary within the Error Categories depending on what
variable failed.
Error
Code
Error Category
Meaning and Corrective Action
0
SUCCESS
Request Succeeded – No Action Needed
1002
INVALID_PARAMETERS
Request has invalid parameters – research
parameter
1003
APPLICATION_PERMISSION_DENIE
D
Partner Principal is missing or invalid
Permission Granting group – Contact
www.motricity.com
18
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
Error
Code
Error Category
Meaning and Corrective Action
[email protected]
1004
PRINCIPAL_PERMISSION_DENIED
Principal denied request, invalid permission –
Contact [email protected]
1005
UNKNOWN_ERROR
System failed, condition unknown – Contact
[email protected]
3000
ACTOR_NOT_FOUND
Actor is not registered in system – Contact
[email protected]
3001
CREDENTIALS_EXPIRED
Partner Principal Credentials have expired –
Contact [email protected]
3003
INVALID_ACTOR
Actor parameter is invalid - Contact
[email protected].
3004
INVALID_PERMISSION_GRANTING_
GROUP
Partner Home is missing for this Partner –
Contact [email protected]
3005
INVALID_PRINCIPAL
Principal parameter is invalid – Contact
[email protected]
3006
INVALID_PRINCIPAL_IDENTITY
Principal Identity parameter is invalid –
Contact [email protected]
3007
MISSING_REQUIRED_METADATA
Authentication processing required metadata –
Contact [email protected]
3008
PRINCIPAL_NOT_FOUND
Principal is not registered in the system –
Contact [email protected]
3009
IDENTITY_NOT_AVAILABLE
Identity is not available – Contact
[email protected]
3010
RESTRICTED_METHOD_STATE
Principal must invoke registered methods
before performing any subsequent operations
– Contact [email protected]
6001
INVALID_CREDENTIALS
Credentials are invalid – Contact
[email protected]
6002
INVALID_EVIDENCE_FORMAT
Evidence does not meet the configured
requirements – Contact
[email protected]
6003
LOGIN_DISABLED
Login is disabled system-wide – Contact
[email protected]
6004
LOGIN_FAILED
Login failed for Principal – Contact
[email protected]
6009
PRINCIPAL_DISABLED
The requested Principal is disabled - Contact
[email protected]
NAMESPACE_DISABLED
Requested Namespace is disabled or Principal
Namespace is disabled – Contact
[email protected]
DATA_ITEM_NOT_FOUND
The specified Data Item is not found in the
given folder – Contact
[email protected]
7010
7013
www.motricity.com
19
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.
8 Document Control
A history of the document
Version
Date
.5
4/19/2004
1.0
5/4/2004
1.1.1
5/5/2004
1.1.2
5/7/2004
1.1.3
5/12/2004
1.1.4
1.2
Notes
Created with documentation and information from
Zon Behrbaum, Chek Lim, Lester Jackson, & Dan
Poppelaars.
Edited for final content
Added in Customization Information with edits from
Chek Lim & Zon Behrbaum
Updated with WSDL URL
Corrected IsUserEntitled logic & changed samples to
non-Camel Case to match code.
Updated to include references to Verizon Wireless’
DCR process.
Updated to reflect lessons learned from first
Premium Content Partner Application.
1.3
Added the implementation process to explain the
process for turning on the PartnerAPI.
1.4
Updates to include clear text authentication, FAQ,
etc.
1.5
Updates to all sections
1.6
Updates
1.7
Updates based on a discussion with Paul
1.8
Edits
1.9
Edits to differentiate INSP-initiated entitlement
checks vs. CP-initiated checks.
2.0
Updated WSDL URL, Soap Samples URL, and support
contact information.
3.0
5/04/2010
Update to include sections 4 and 5. Updated links
and contacts.
3.1
5/16/2010
Update
3.2
6/15/2010
Update with Custom Configuration Parameters, Free
vs. Premium Product with API, Contact Info.,
formatting.
3.3
7/19/2010
Update Section 2: Update diagram to clarify use of
API.
Update Section 3: Making terminology referencing
content and partner consistent.
Update to Section 5: Replacing timeline with content
management process
3.4
7/21/2010
Updates to section 3 with Verizon Developer
Community link.
www.motricity.com
20
© 2006 Motricity, Inc. All rights reserved. This document is protected by U.S. and international copyright laws
and conventions. Motricity and Fuel are trademarks of Motricity, Inc. All trademarks and registered marks of
products and companies referred to in this document are protected.