FAQ

From ePrize Developers Wiki

Current revision

This is a list of Frequently Asked Questions about using ePrize Web Services.

What's the bare minimum I need to know?

ePrize Web Services is a set of RESTful service calls designed to provide application developers with straightforward access to ePrize promotion back end services. The services provide promotion functionality such as profile registration, login, awarding of a game play, playing a game, awarding sweepstakes entries, and are designed to be seamlessly integrated into your online campaign.

What is BReWS?

BReWS is Engineering's name for ePrize Web Services. It stands for Better RESTful ePrize Web Services. Now that that's covered, we'll be using BReWS for the rest of the FAQ.

How do I get started?

The absolute shortest path: Call ePrize at 1(877) 837-7493 or email us at questions@eprize.com to get an API key. Access your service at http://code.eprize.com/v1/{apikey}/.

How do I talk to the experts?

We are the experts, and we are all subscribed to our BReWS mailing list. Read about that here: Webservices Mailing List

Does BReWS provide the logic that determines if a consumer should earn an award, like a sweepstakes entry or game play?

You are in charge of when the user should get the sweeps entry or game play. BReWS will determine whether or not the user is a winner.

How does BReWS handle Invalid Email Format, Address Not Verified, and Too Young to Play?

We will send back a validation error for Invalid Email or Invalid Age. Address Not Verified will not be sent back to the client. Any address that does not pass verification is marked ineligible behind the scenes.

How does BReWS handle Already registered or Already played today?

When someone is Already registered and tries to register again, a duplicate registration error will be generated. It is the client's responsibility to log people in if they have already registered. (This is not built-in to the API because it makes the API less flexible.) The API will not send back Already played today, but the client can look at the history of awarded plays and see when a person has played.

Can I use CAPTCHA with BReWS?

Yes. See: CAPTCHA

Why are the URLs so difficult to parse? What patterns should I use to extract the data I need from a URL?

Discoverability is a key piece of the REST architecture.

When you get a URI back from a REST call, use that URI directly and do not try to parse it. There's absolutely no guarantee that the resource will stay in the same format. The only thing you should ever do is take a relative URL, i.e. the URI has no hostname or scheme name, and add the hostname and scheme name that you have been assigned. That is necessary to make an HTTP request. We'll be adding more metadata such as actions you can take on those game URIs in future versions of the API.

For example, a query for your games using a "v1" REST call may return "v2" game resources if the interface is compatible with "v1". We may also change the format of a UUID, assign you a new temporary API key, or relocate the game resources to somewhere other than "game". All of these changes would probably break your code.

A good way to understand this is to think of your code as a web browser. It makes a request, then uses the return result to make the next request. At no time does a web browser try to parse a URL and synthesize a new URL to request. This gives you great flexibility in supporting future upgrades to the server and probably simplifies your code at the same time.

Can you do rewarded and unrewarded Tell a Friend emails?

Yes, you can incentivize how ever you want. A promotion could award an extra game play on Tell a Friend, or when answering a survey, or winning a high score. The options are limited more by law than by the API. Make sure you are well versed in CAN-SPAM and other relevant laws and conventions before sending incentivized emails.

How do I access my promotion data?

Full access to promotion data is handled through the ePrize Client Portal. Information on accessing that should have been provided when you received your API Key. The API will have a limited set of calls available for accessing promotion metrics data.

How do I know who wins a game?

Game plays that win will result in an immediate message back to you that the game play was a winner. You turn that into the messaging and creative you want to show your lucky winner. BReWS has no copy, images, or prize names.

Does BReWS choose Sweepstakes Winners?

Yes, it automatically selects sweepstakes winners based on the sweepstakes awarding schedule submitted at API Key creation.

Can I run multiple promotions off the same registration base?

You can choose to use one API Key for all profile storage, then separate API Keys for all the promotion games. If it's important to differentiate one promotion from another based on anything other than registration date, the client must include a promotion name when registering someone for a promotion.

If I have to store my own data, what's the value of BReWS to me?

You only need to be responsible for your website text and creative, not individual profile data or game information. All the logic of profile validation, storage, security, and game play happens on ePrize's secure systems. This allows you to focus on what's important, be that low-cost mass-production of a simple promotion template, or wildly complex integrations with existing web sites.

How can ePrize store all the data if I have to decide when game plays are awarded? Isn't that weird?

You always decide when game plays are awarded and ePrize always decides who wins. In deciding to award plays, you can ask ePrize for a consumer's profile, or use information from their own computers. For example, if you built a typical microsite with a login page, the end user would enter their email on the login, then the microsite would ask ePrize if the email was already registered. If it was registered, your microsite could make decisions using what's contained in the profile. If the email wasn't registered, the microsite would show the registration page.

This is just one simple possibility - the sky's the limit! What if the microsite is embedded in a bigger web site with a shopping cart? The site doesn't display a login or registration page because it already asked for that stuff as part of the check-out flow. It automatically sent ePrize a registration using the shopper id instead of an email. Plays could be awarded based on what's in the shopping cart, what's in the profile, or any combination. The client's web site decides what plays should be awarded, then tells ePrize to award the plays.