IsUserEntitled API - Verizon Developer Community

voraciousdrabSoftware and s/w Development

Dec 14, 2013 (7 years and 7 months ago)

320 views












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 compan
ies referred to in this document are protected.










































Content Partner’s Guide to
IsUserEntitled API


Version 3.4

July 22
, 2010













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 compan
ies referred to in this document are protected.

C
ONTENTS


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

Cont
act Information

................................
................................
................................
................

16

7

Appendix

................................
................................
................................
...........................

16

8

Document Control
................................
................................
................................
...............

20






























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 compan
ies 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 A
pplication Programming Interface (A
PI
) 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 f
or each of the Content
Partner’s applications.
See section 5


Implementation Process for details.




How to Use This Document

To provide you an

understand
ing of

the API and ho
w 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 IsUser
Entitled 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
authori
zation 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











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 compan
ies 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
red
irect unauthorized users to

subscription landing page

url

returned in the API response
.

















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 compan
ies referred to in this document are protected.

2.2

Request Sequence



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
Content
Partner

is valid, and the subscriber
has
access to premium content
. If
both are valid
, the
n

the
API
responds to the Content
Partner
that the
subscriber

is authorized (3). If the
subscriber

does not have

access to
premium content,
the
n 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
S
ubscriber
(4).

2.2.5


Subscrib
er
not Entitled

The Content Partner redirects subscriber to subscription landing page.

(4)














www.motricity.com











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 compan
ies 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 fo
und 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

Partner@MOTRPartner.com

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==



-

or
-


My_P@$$w0rd

UserIdentity

Max
Length
320;

String

S
ubscriber’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














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 compan
ies 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

S
ubscriber’s
source IP address
-

this is the value in the
subscribe
r’s
HTTP header from the
subscrib
er’s
request. IPs are assigned
dynamically by Verizon Wireless.
This must be from a currently active
session.


“HTTP_USERIP=” is the parameter
to look for in the HTTP

HEADER.


69.78.188.155



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 i
s 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 enc
rypted

(HTTP), then the evidence token
hash must be used

as follows
.


The evidence token hash is an A
SCII string with the following format:




DateTime + ‘:’ + Base64(MD5(DateTime + PartnerIdentity + Password))




DateTime


=

UTC Date/Time with form MMddyyyyHHmmssff



PartnerIdentity

=

Partner@
MOTR
Partner
.com



Password


=

Clear
-
text password


2.
6
.1
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











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 compan
ies referred to in this document are protected.


MM

two
-
digit month.



01
-
12
.


dd

two
-
digit day of month.


01
-
31


yyyy

four
-
digit year.



2005+


HH

two
-
digit hour



00
-
23


mm

two
-
digit minute



00
-
59


ss

two
-
digit second


00
-
59


ff

two
-
digit 1/100
th
‘s of a second

00
-
99


Examples of this date format are as follows:


Midnight
Jan 1
st

2005:


0101200500000000

1:23:45.67 Jan 23
rd
, 2005


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

P
rimary 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

Partner@MOTRPartner.com

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)

0123200519560000Partner@MOTRPartner.comP@55Word

Hash string (after encoding)

qhJ+fJrVnctM2Wv5MUXbBA==

Final Evidence string

0123200519560000:

qhJ+fJrVnctM2Wv5MUXbBA==


Partner Evidence

Example #2

Evidence Field

Value

Partner Identity

Partner@MOTRPartner.com

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)

1230200507000000Partner@MOTRPartner.comP@55Word












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 compan
ies 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

Partner@MOTRPartner.com

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)

1122200506445599Partner@MOTRPartner.comP@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
‘Us
erEntitlementApproved’ 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 e
rror.



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
=
敮ti瑬敭敮琠
m
整桯搮⁕si湧⁴=is整桯搬h慮a慵瑨敮eic慴a搠
䍯湴e湴n
m慲瑮敲
=
c慮=valid慴攠e=
subscriber’s
=
敮瑩tl敭敮琠瑯⁡=s敲vic攮

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











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 compan
ies referred to in this document are protected.

IsUserEntitled Output
-

Validate
subscriber’s

entitlement
m
ethod. Using this method, an authenticated
Content
Partner

can validate a
subscriber’s

entitlement to a service.

Parameter & Sequence

Length/Type

Description

ErrorDescription

ErrorCode


LandingPage

description
-

s:string

ErrorCode
-
Presently
4 digit integer s:int

LandingPage
-
s: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.




3

Linking to
Con
tent from VZW Mobile Web
Portal

















































































































































































































































































































































































































































































































































































There are options for h
ow a link to a premium
/non
-
premium

content

site can be set u
p 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 VZ
W 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 si
te in the
Verizon
Developer Community site
.


Linking to
Non
-
Premium Content site

No entitlement check is performed on the VZW
P
ortal before redirecting to a
non
-
premium
content

page on the
VZW
Content
P
artner site. It is up to the
C
ontent
P
artner 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
p
ortal users choose to access a premium
c
ontent
site
, the appropriate entitlement to the conte
n
t

is verified
. If access is granted,
the
request will be redirected

to the premium
c
on
tent
site
, optionally appending customization
information

(i.e.

p
ortal user
’s

zip code)

to the URL. Upon receipt of the redirected request, the











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 compan
ies 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

P
ortal user. For example, a
p
ortal user’s
postal code can be used to limit the
scope of the premium content to a particular are
a that is more relevant to the p
ortal 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 P
artner

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 Partne
r site URL.
Please contact VZW Partner Management at
micontentpartners@verizonwireless.com

if you’d like to get further details and/or implement
customized parameters.



3.
1
.2
Zip Code Paramet
ers

The following table contains supported parameters that a Premium Content P
artner

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

Z
IP (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











1
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 compan
ies 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 th
a
n 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

provid
e premium
content sites

to VZW subscribers.
This process
focuses on

VZW Content Partner’s implementing
support of t
he IsUserEntitled API and
VZW’s publication
o
f premium content sites on the Mobile
Web portal. Content Partner
s should adhere to the following process:



Process Steps

Description

Existing VZW
Con
tent
Partner submits
DCR
request to

implement
Premium Content

Content Partner submits a

completed DCR to Verizon Wireless
.
Please contact VZW Partner Management at
micontentpartners@verizonwireless.com

to obtain submission
requirements (i.e. submission dates to meet release dates).

VZW
will process DCR and
Price Plan of Premium
Content

T
he DCR and
Price Plan of the

Content Partner’s
premium c
ontent

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
pr
emium content to Content Partner.


Premium Content

is added
to
the
VZW Portal

and
Tested

T
he Content Partner’s

premium content URLs shall

be
tested
in
pre
-
production

environments

u
sing
various V
erizon Wireless
devices.

Premium Content is
published to
VZW
Production environment

During Content Release date,
URL l
inks to Content Partner’s
premium content
sites

are
published to
VZW’s p
roduction
environment and are

made
available
to VZW subscribers.












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 compan
ies referred to in this document are protected.

Process Steps

Description

Post Release



Within 14
days of Premium Content
Release,
Content Partner
validates
entitlement
checks

T
he Content Partner is
required

to insure
their site

is providing
appropriate entitlement check
s 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 con
tent.



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:
Partner@MOTRPartner.com

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
micontentpartners@verizonwireless.com



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 err
or message starts with your Partner Identity (e.g. “Partner@
MOTR
Partner.com:email :
Cannot….”), the application login was successful and it is a user login issue. See
Why is my Portal
user login fai
ling?

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 s
upplied
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 (HTT
P), the Identity hash must be used. For secure requests











www.motricity.com











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 compan
ies referred to in this document are protected.

(HTTPS/SSL) clear text passwords must be used. If your application evidence type does not
match your access scheme, login will fail.

6
.4 Clear
-
text password

If you are using a clear text passwo
rd, 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 m
ost
common scenarios:

Identity Hash
Problem

Description /
Remedy

Incorrect Protocol
for evidence type

If your IsUserEntitled request uses HTTPS/SSL, the Identity hash
authentication will fail. If HTTPS/SSL is used, use your clear
-
text
password for partner identity.

Invalid Partner
Identity


Be sure the Partner Identity (e.g.
Partner@
MOTR
Partner.com
)
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.

Invalid Partner
Password


Be sure the partner password used to construct the id
entity 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
VzwPartnerSupport@motricity.com


Incorrect date
string format

The format of the dat
e 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.


Incorrect date time
zone

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.

Incorrect server
time


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
ti浥mE睩thin⁳e癥r慬⁳econd猩⸠ ft⁩猠re捯浭ended⁴ 慴
you⁳et⁵
the慣 ine⁳u捨⁴h慴⁴he⁣lo捫⁷ ll⁳t慹⁩a⁳祮挠慵to浡ti捡汬礮

corⁱ i捫⁲eferenceI⁡ 慣aur慴e⁴ 浥mre慤ing慹⁢ bt慩ned
晲o洠
http://www.time.gov












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 compan
ies referred to in this document are protected.

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
.


6
.6 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 Po
rtal. 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 use
r 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,
con
tact VZW Partner Management at
micontentpartners@verizonwireless.com
.


6
.7 Why is UserEntitlementApproved always false?

The ‘UserEntitlementApproved’ value will only be true if these three f
actors 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 Prem
ium 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











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 compan
ies referred to in this document are protected.


Contact Information

For any Premium
Content
Partner support issues or questions, please contact Motricity at

VzwPartnerSupport@motricity.com


When reporting errors please include as much information as is available, including:

Date and time the e
rror 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 devi
ces provide the VZW Mobile Web experience. Only VZW
gateway devices are able to display premium content.

Parameters

Gateway

Non
-
Gateway

RIM

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











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 compan
ies 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/envelop
e/">


<soap:Body>


<IsUserEntitled xmlns="http://www.InfoSpace.com/Partners/">


<PartnerIdentity>string</PartnerIdentity>


<PartnerEvidence>string</PartnerEvidence>












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 compan
ies referred to in this document are protected.


<UserIdentity>string</UserIdentity>


<UserEvidence>string</UserEvi
dence>


<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


<?xm
l 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/entitlem
entfailed.htm?vendorID=777666&amp;productID
=123456&amp;productVersion=12312&amp;UID=6b740930
-
6300
-
406e
-
873c
-
9b364a0876e4</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











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 compan
ies referred to in this document are protected.

Error
Code

Error Category

Meaning and Corrective Action

vzwpartnersupport@motricity.com


1004

PRINCIPAL_PERMISSION_DENIED

Principal denied request, invalid permission


Contact
vzwpartnersupport@motricity.com

1005

UNKNOWN_ERROR

System failed, condition unknown


Contact
vzwpartnersupport@motricity.com

3000

ACTOR_NOT_FOUND

Actor is not registered in system


Contact
vzwpartnersupport@motricity.com

3001

CREDENTIALS_EXPIRED

Partner Principal Credentials have expired


Contact
vzwpartnersupport@motricity.com

3003

INVALID_ACTOR

Actor parameter is invalid
-

Contact
vzwpartnersupport@motricity.com
.

3004

INVALID_PERMISSION_GRANTING_
GROUP

Partner Home is missing for this Partner


Contact
vzwpartnersupport@motricity.com

3005

INVALID_PRINCIPAL

Principal parameter is invalid


Contact
vzwpartnersupport@motricity.com

3006

INVALID_PRINCIPAL_IDENTITY

Principal Identity parameter is invalid


Contact
vzwpartnersupport@motricity.com

3007

MISSING_REQUIRED_METADATA

Authentication processing required metadata


Contact
vzwpartnersupport@motricity.com

3008

PRINCIPAL_NOT_FOUND

Principal is not registered in the system


Contact
vzwpartnersupport@motricity.com

3009

IDENTITY_NOT_AVAILABLE

Identity is not available


Contact
vzwpartnersupport@motricity.com

3010

RESTRICTED_METHOD_STATE

Principal must invoke registered methods
before performing any subsequent operations


Contact
vzwpartnersupport@motricity.com

6001

INVALID_CREDENTIALS

Credentials are invalid


Contact
vzwpartnersupport@motricity.com

6002

INVALID_EVIDENCE_FORMAT

Evidence does not meet the configured
requirements


Contact
vzwpartnersupport@motricity.com

6003

LOGIN_DISABLED

Login is disabled system
-
wide


Contact
vzwpartnersupport@motricity.com

6004

LOGIN_FAILED

Login failed for Principal


Contact
vzwpartnersupport@motricity.com

6009

PRINCIPAL_DISABLED

The requested Principal is disabled

-

Contact
vzwpartnersupport@motricity.com

7010

NAMESPACE_DISABLED

Requested Namespace is disabled or Principal
Namespace is disabled


Contact
vzwpartnersupport@motricity.com

7013

DATA_ITEM_NOT_FOUND

The specified Data Item is not found in the
given folder


Contact
vzwpartnersupport@motricity.com















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 compan
ies referred to in this document are protected.

8

Document Control


A history of the document


Version

Date

Notes

.5

4/19/2004

Created with documentation and information from
Zon Behrbaum, Chek Lim, Lester Jackson, & Dan
Poppelaars.

1.0

5/4/2004

Edited for final
content

1.1.1

5/5/2004

Added in Customization Information with edits from
Chek Lim & Zon Behrbaum

1.1.2

5/7/2004

Updated with WSDL URL

1.1.3

5/12/2004

Corrected IsUserEntitled logic & changed samples to
non
-
Camel Case to match code.

1.1.4


Updated to
include references to Verizon Wireless’
DCR process.

1.2


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 pr
ocess

3.4

7/21/2010

Updates to section 3 with Verizon Developer
Community link.