The FlickRocket platform consists of a shop frontend, an access backend, administration, preparation and client side modules. This document explains how to replace the shop frontend with a custom shop system while maintain all the functionality of the other modules.

The functionalities of the different modules are a follows:

Module	Responsibility
Shop Frontend	Presents available content to the customer, includes shopping cart functionality and performs the payment processing. After the purchase completes, the user is redirected to the Access Backend.
Access Backend	Enables the customer to access content by requesting software to be installed (if required) and offering access functionality using the installed software.
Administration	Enables the content owner to manage the content, licenses, pricing and all related shop functionality.
Preparation	Enables the customer to ingest content into the platform and does the required content preparation steps to support all different platforms.
Client Side	Works based on the Access Backend and enables the customer to access purchased content.

The shop frontend can be replaced by different shop systems. However, it is important to understand that these shop frontends should have at least the following options for being able to be used as replacement:

Needs to be able to present different license options (e.g. rental and purchase) for products
Needs to offer a login function for existing customers (the access to the content is managed by FlickRocket).
Needs support for SSL to accept payments
Needs to be able to use SOAP requests to communicate with the FlickRocket Access Backend
Customers must be forced to specify at least an email and password

The following explains the web services which must be used to integrate the custom shop frontend with the FlickRocket platform.

URLs

The FlickRocket OnDemandOrder web service (SOAP) can be accessed at the URLs below. We provide C# sample code but PHP may also be used.

Service URL: https://www.flickrocket.com/Services/OnDemandOrder/service.asmx

Service WSDL: https://www.flickrocket.com/Services/OnDemandOrder/service.asmx?WSDL

Shop Related Web Service Functions

Shop Related Web Service functions are functions which work based on a Shop user which is granted access to individual content items and licenses.

CheckAccount()

The CheckAccount function checks if the account data is valid and can access a certain theme.

bool CheckAccount(string EMail, string Password, int ThemeID, out int ErrorCode)

Return value	Returns true on success
EMail	FlickRocket admin user email (requires “shop management” right)
Password	FlickRocket admin user password
ThemeID	The identifier of a theme. Themes are used by other API functions and are defined in the FlickRocket web interface. ID 1 is a default theme which is accessible to all users.
ErrorCode	Out Param Returns an ErrorCode if CheckAccount failed: -1: FlickRocket User not found -2: FlickRocket User valid but theme does not exist -3: FlickRocket User valid but has no access rights to theme -4: API not enabled

CreateShopOrder()

The CreateShopOrder function is used to communicate new content rights for a user to the FlickRocket platform. Basically the rights can be specified in of two ways:

By specifying the content and associated license

This is typically used for shop integration in which the user has selected and paid for content). The Items node is used to specify content and associated license. If it is empty, it can also be used to create just a new user.

By specifying one or more UnlockCodes to be redeemed

This is typically used for scenarios where a web site offers code redemption. The UnlockCodes node is used to specify UnlockCodes to be redeemed.

CreateShopOrder may only the used with one of the before mentioned options at a time. Using multiple will result in an error.

bool CreateShopOrder(string EMail, string Password, string XML, out int ErrorCode)

Return value	Returns true on success
EMail	FlickRocket admin user email (requires “shop management” right)
Password	FlickRocket admin user password
XML	XML formatted content/rights, group information or UnlockCodes
ErrorCode	Out Param Returns an ErrorCode if CreateShopOrder failed: -1: FlickRocket User not found -2: Malformed XML -3: “Order” Root in XML not found -4: Wrong email or password in XML -5: Unknown Error -6: No Customer Password in XML -7: Invalid UnlockCode(s) -8: Expired UnlockCode(s) -9: UnlockCode(s) usage exceed -10: API Usage not allowed. Please contact FlickRocket. -11: Invalid project -12: Project deleted -13: New user cannot be created with PasswordHash -14: No permission to create order for this product -15: Double order

The XML must be constructed as follows:

Node Identifier	Value Type	Description
Order
TransactionID	Alphanumeric (Mandatory)	TransactionID (supposed to be unique) to map this order in FlickRocket with an order in the 3^rd party shop frontend. The TransactionID is reported in the CSV exports.
EMail	Email (Mandatory)	The email address of the customer. To access the content via the Access Backend or Client Side software, this email needs to be used.
Password	Alphanumeric (Optional)	The clear text password of the customer. To access the content via the Access Backend or Client Side software, this password needs to be used. For new customers this field must be used. “Password” or “PasswordHash” needs to be present in the XML.
PasswordHash	Alphanumeric (Optional)	The SHA-1 password of the customer. To access the content via the Access Backend or Client Side software, this password needs to be used. For existing customers this field or the plain text Password might be used. “Password” or “PasswordHash” needs to be present in the XML.
ThemeID	Numeric (Mandatory)	The ThemeID of the theme to be associated with the order. On company may have multiple themes with different content. For any web interface design elements the user is presented, this theme is used. The ThemeIDs are listed in the FlickRocket admin interface under Shop -> Themes -> Manage design and texts.
Firstname	Alphanumeric (Optional)	First name of the customer
Lastname	Alphanumeric (Optional)	Last name of the customer
Address1	Alphanumeric (Optional)	Address of the customer
Address2	Alphanumeric (Optional)	Additional address information
City	Alphanumeric (Optional)	City
ZIP	Alphanumeric (Optional)	ZIP code
State	Alphanumeric (Optional)	State for US/CA only. Specified in two characters, e.g. "CA" for Califonia
Country	Alphanumeric (Optional)	The two character country code. E.g. "US" for United States
Language	Alphanumeric (Optional)	The two character language code. E.g. "en" for English
Items	Item Node (Optional)	A list of item nodes which define the actual ordered items and associated licenses.
Item		If no Items node is present, only the user is created on the FlickRocket platform.
ProjectID	ProjectID (Mandatory)	The ProjectID of the content. The format of ProjectIDs is always ABCD-ABCD-ABCD-ABCD and a list of all ProjectIDs are listed under Projects -> List projects.
LicenseID		The LicenseID of the content. The LicenseIDs are listed under Shop -> Licenses -> List licenses.
Count	Numeric (Mandatory)	The number of ordered licenses for the project.
HD	Numeric (Optional)	Must be “1” if the content is video and the HD version is ordered. Muist be “0” if the content is video and the SD version is ordered.

UnlockCodes	UnlockCode Node (Optional)	A list of UnlockCodes to be redeemed.
UnlockCode	Alphanumeric (Mandatory)	One Unlockcode to be redeemed

Sample XML for items:

<?xml version="1.0" encoding="utf-8" ?>

<Order>

<EMail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!</EMail>

<Password>password</Password>

<Item>

</Item>

<Item>

</Item>

</Items>

</Order>

or sample XML for UnlockCode redemption:

<?xml version="1.0" encoding="utf-8" ?>

<Order>

<EMail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!<;/EMail>

<Password>password</Password>

</UnlockCodes>

</Order>

CheckUserExists()

The CheckUserExists function is used to check if a user is already known to the backend. This is usually done in advance of calling the CreateShopOrder function to make sure the user is valid.

The function returns true if the email address is unknown or the email address is known and the password matches. In both cases the CreateShopOrder function can be used with the identical email and password.

The function returns false in case of an error. In case the ErrorCode is -5 the email is known to the backend but the password does not match. In this case the calling application should display a message to the user that his email is already known from his purchases in the shop list returned in the Companies parameter and he has to use the matching password.

bool CheckUserExists(string EMail, string Password, string XML, out int ErrorCode, out List<string> Companies)

Return value	Returns true if the email address is unknown or the email address is known and the password matches
EMail	FlickRocket admin user email (requires “shop management” right)
Password	FlickRocket admin user password
XML	XML formatted user data
ErrorCode	Out Param Returns an ErrorCode if CheckUserExists failed: -1: Invalid User -2: Malformed XML -3: Customer Node not found -4: Password or PasswordHash Node not found -5: Email found but wrong Password. The companies from which the user data is known is available in the Companies parameter -6: Empty user password

The XML must be constructed as follows:

Node Identifier	Value Type	Description
Customer
EMail	Email (Mandatory)	The email address of of the customer to be checked.
Password	Alphanumeric (Optional)	The clear text password of the customer. “Password” or “PasswordHash” needs to be present in the XML.
PasswordHash	Alphanumeric (Optional)	The password hash of the customer. “Password” or “PasswordHash” needs to be present in the XML.

Sample XML:

<?xml version="1.0" encoding="utf-8" ?>

<EMail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!<;/EMail>

<Password>password</Password>

</Customer>

CheckPreviewExists()

The CheckPreviewExists function is used to check if a preview/trailer exists for the specified project. The function returns true if a preview exists and false if no preview exists.

If a preview exists, it can be played back by navigating (typically in a pop up) to the following link with passing the ProjectID.

http://www.flickrocket.com/services/OnDemandOrder/Preview.aspx?PID=<ProjectID>

bool CheckPreviewExists(string EMail, string Password, string ProjectID)

Return value	Returns true if a preview exists and false if no preview exists
EMail	FlickRocket admin user email (requires “shop management” right)
Password	FlickRocket admin user password
ProjectID	The ProjectID of the project for which the preview availability is checked

Sample URL:

http://www.flickrocket.com/services/OnDemandOrder/Preview.aspx?PID=ABCD-ABCD-ABCD-ABCD

ChangeCustomerPassword()

The ChangeCustomerPassword function is used to update the FlickRocket platform with an updated password in case the user changes his password.

In case the original password is not known (e.g. for a “forgotten password” function) where the user is externally verified (e.g. by sending an email with a confirmation link) the function can be used with the magic value “_use_only_after_external_validation_” as original password parameter. However, this works only if the company using the API has created the user or has sold items to the user. THIS MUST NOT BE USED FOR REGULAR PASSWORD CHANGES.

bool ChangeCustomerPassword(string EMail, string Password, string XML, out int ErrorCode)

Return value	Returns true on success
Email	FlickRocket admin user email
Password	FlickRocket admin user password (requires “shop management” right)
XML	Formatted user data
ErrorCode	Out Param Returns an ErrorCode if ChangeCustomerPassword failed: -1: FlickRocket user not found -2: Malformed XML -3: “Customer” Root in XML not found -4: Customer user not found -5: No Password or PasswordHash in XML -6: No NewPassword or NewPasswordHash in XML -7: New PasswordHash not supported

The XML must be constructed as follows:

Node Identifier	Value Type	Description
Customer
EMail	Email (Mandatory)	The email address of of the customer for which the password is changed.
Password	Alphanumeric (Optional)	The old clear text password of of the customer (for regular passord changes) or “_use_only_after_external_validation_” if the orginal password is unknown and the email has been externally validated, e.g. by sending an email with a confirmation link. “Password” or “PasswordHash” needs to be present in the XML.
NewPassword	Alphanumeric (Optional)	The new clear text password of the customer. “NewPassword” or “NewPasswordHash” needs to be present in the XML.
PasswordHash	Alphanumeric (Optional)	The old SHA-1 password of the customer. “Password” or “PasswordHash” needs to be present in the XML.

Sample XML for regular password change:

<?xml version="1.0" encoding="utf-8" ?>

<EMail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!<;/EMail>

<Password>password</Password>

<NewPassword>newpassword</NewPassword>

</Customer>

Sample XML for password reset after external email validation:

<?xml version="1.0" encoding="utf-8" ?>

<EMail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!<;/EMail>

<Password>_use_only_after_external_validation_</Password>

<NewPassword>newpassword</NewPassword>

</Customer>

ChangeCustomerEmail()

The ChangeCustomerEmail function is used to update the FlickRocket platform with an updated email in case the user changes his email.

bool ChangeCustomerEmail(string EMail, string Password, string XML, out int ErrorCode)

Return value	Returns true on success
EMail	FlickRocket admin user email
Password	FlickRocket admin user password (requires “shop management” right)
XML	Formatted user data
ErrorCode	Out Param Returns an ErrorCode if ChangeCustomerEmail failed: -1: Invalid user -2: Invalid XML -3: Customer node in XML not found -4: Customer not found -5: Password node in XML not found -7: New email node in XML not found -8: New email already exists

The XML must be constructed as follows:

Node Identifier	Value Type	Description
Customer
EMail	Email (Mandatory)	The email address of the customer for which the email is changed.
NewEMail	Email (Mandatory)
Password	Alphanumeric (Optional)	The clear text password of the customer. “Password” or “PasswordHash” needs to be present in the XML.
PasswordHash	Alphanumeric (Optional)	The SHA-1 password of the customer. “Password” or “PasswordHash” needs to be present in the XML.

Sample XML:

<?xml version="1.0" encoding="utf-8" ?>

<EMail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!<;/EMail>

<NewEMail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!<;/NewEMail>

<Password>password</Password>

</Customer>

PrepareLoginEx()

The PrepareLoginEx function is used to get a unqiue URL for the Access Backend which can be embedded via iframe or to which the user can be redirected after purchase or at login.

bool PrepareLoginEx(string EMail, string Password, string XML, int ThemeID, out int ErrorCode, out string sURL)

Return value	Returns true on success
EMail	FlickRocket admin user email (requires “shop management” right)
Password	FlickRocket admin user password
XML	XML formatted user description
ThemeID	The Id of the theme to be used
ErrorCode	Out Param Returns an ErrorCode if PrepareLogin failed: -1: FlickRocket user not found -2: Malformed XML -3: “Customer” root in XML not found -4: Customer user not found -5: Email and password do not match -6: Invalid theme
sURL	Returns a URL to be embedded via iframe or to be redirected to.

The XML must be constructed as follows:

Node Identifier	Value Type	Description
Customer
Email	Email (Mandatory)	The email address of the customer who should be logged in.
Password	Alphanumeric (Optional)	The clear text password of the customer. “Password” or “PasswordHash” needs to be present in the XML.
PasswordHash	Alphanumeric (Optional)	The SHA-1 password of the customer. “Password” or “PasswordHash” needs to be present in the XML.

Sample XML:

<?xml version="1.0" encoding="utf-8" ?>

<EMail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!<;/EMail>

<Password>password</Password>

</Customer>

GetProjects()

The GetProjects function is used to retrieve a list of projects. The function returns true if a valid list of projects is returned.

bool GetProjects (string EMail, string Password, int ThemeID, out List<string> Projects, out int ErrorCode)

Return value	Returns true if the list of projects is returned and can be used
Email	FlickRocket admin user email (requires “shop management” right)
Password	FlickRocket admin user password
ThemeID	The ThemeID to which the projects needs to be assigend which will be returned back. If theme is -1, all projects are returned.
Projects	Out Param For each project the following structure is returned: public struct stProject { public string LongProjectID; public string Name; public DateTime CreationDate; public eContentType ContentType; public bool Complete; } public enum eContentType { Unknown = -1, fluxDVD = 1, Silverlight = 2, //Reserved WebProject = 3, Software = 4, AudioCollection = 5, Physisch = 6, //Physical item fluxPackage = 7, ProjectCollection = 8, fluxDVD_HD = 9, SmartTV_Video = 10, //Reserved SmartTV_Audio = 11, //Reserved ProjectBased = 15, //Reserved eBook = 16, }
ErrorCode	Out Param Returns an ErrorCode if GetProjects failed: -1: Invalid User -2: No projects found -3: Unknown error

GetLicenses()

The GetLicenses function is used to retrieve a list of licenses. The function returns true if a valid list of licenses is returned.

bool GetProjects (string EMail, string Password, out List<stLicense> Licenses, out int ErrorCode)

Return value	Returns true if the list of licenses is returned and can be used
Email	FlickRocket admin user email (requires “shop management” right)
Password	FlickRocket admin user password
Licenses	For each license the following structure is returned: publicstructstLicense { publicint ID; publicstring Name; }
ErrorCode	Out Param Returns an ErrorCode if GetLicenses failed: -1: Invalid User -2: No licenses found -3: Unknown error

GetThemes()

The GetThemes function is used to retrieve a list of themes. The function returns true if a valid list of themes is returned.

bool GetThemes (string EMail, string Password, out List<stTheme> Themes, out int ErrorCode)

Return value	Returns true if the list of themes is returned and can be used
Email	FlickRocket admin user email (requires “shop management” right)
Password	FlickRocket admin user password
Themes	Out Param For each license the following structure is returned: public struct stTheme { publicint ID; publicstring Name; public string Domain; public string Settings; }
ErrorCode	Out Param Returns an ErrorCode if GetThemes failed: -1: Invalid User -2: No themes found -3: Unknown error

GetTrailer()

The GetTrailer function is used to retrieve a list of trailers for projects. Please note that trailers are optional and may not exist. If a trailer does not exist, it is not returned as part the stTrailers list. The function returns true if a valid list of trailers is returned.

bool GetTrailer (string EMail, string Password, List<string> ProjectIDs, out List<stTrailer> Trailer, out int ErrorCode)

Return value	Returns true if the list of trailers is returned and can be used
Email	FlickRocket admin user email (requires “shop management” right)
Password	FlickRocket admin user password
ProjectIDs	A list of the ProjectIDs for wich trailers should be returned. If no ProjectID is specified, all trailers are returned.
Trailer	Out Param For each trailer the following structure is returned: public struct stTrailer { public string URL; public string ProjectID; }
ErrorCode	Out Param Returns an ErrorCode if GetTrailer failed: -1: Invalid User -2: No trailer(s) found -3: Unknown error

User data changes syncback

The following describes the process how FlickRocket communicates user information changes (E-Mail/Password changes) to 3rd party shop platforms which are related to the user whose information is updated.

To utilize this functionality, a number of settings has to be done in the related App Settings of the FlickRocket Backend. This is done in the admin interface under Extensions / Mage Apps / <Settings for the App>.

Setting	Description
UserDataChangeURL	The URL to which the change notifications get requests are sent.
Hash Type	The type of the password has to be communicated for password changes.
Secret	The secret to be used for signing the request. This must also be known on the receiving end.

If a change in the email or password occurs, a get request to the UserDataChangeURL with the following parameters is invoked.

Parameter	Description
user_token	token identifying the customer (reserved / empty)
email	email address identifying the user (mandatory)
new_email	new email address of the user (optional)
old_pw_hash	old password hash of the user (optional but required for verification purposes if new new_pw_hash is specified)
new_pw_hash	new password hash of the user (optional)
pw_hash_type	int identifying the password hash algorithm (required if old_pw_hash and/or new_pw_hash is specified) 1 = SHA1 2 = MD5 (Salted) 5 = SHA_256 6 = Plain (requires permission)
signature	signature to validate the post as described below

The signature used is calculated as SHA-1 hash (hexadecimal output) from the request parameters. The first parameter has to be your secret, followed by the parameters ordered alphabetically by their names. Optional arguments that are used (have value) must be contained in the signature calculation. Optional arguments that are not used must not be contained in the signature calculation.

It is mandatory to convert arguments values into UTF-8 before computing the signature.

Example:

signature = sha1_hex( secret + ":email=" + email + ":new_email=" + new_email + ":new_pw_hash=" + new_pw_hash + ":old_pw_hash=" + old_pw_hash + ":pw_hash_type=" + pw_hash_type)

Example calculation:

Value	Description
Secret	BddJxtUBkDgFB9kj7Zwguxde4gAqha
email	Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!
new_email	Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!
new_pw_hash	a2a1e3f447524d73729d972db3f837c5:MD
old_pw_hash	cc3469055de99a54451507fdf66a3a00:MD
pw_hash_type	int identifying the password hash algorithm (required if old_pw_hash and/or new_pw_hash is specified)

Signature calculation using the values above:

signature = sha1_hex(BddJxtUBkDgFB9kj7Zwguxde4gAqha:email=Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!:new_email=Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!:new_pw_hash=a2a1e3f447524d73729d972db3f837c5:MD:old_pw_hash=cc3469055de99a54451507fdf66a3a00:MD:pw_hash_type=4) => a043071d3db1d3bbacee04e1eaf07da0d3ab1d17

The request then is:

https://sample.update.com/update?email=Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!&new_email=Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!&new_pw_hash=a2a1e3f447524d73729d972db3f837c5:MD&old_pw_hash=cc3469055de99a54451507fdf66a3a00:MD&pw_hash_type=4&signature=a043071 d3db1d3bbacee04e1eaf07da0d3ab1d17

SOAP API (deprecated)

URLs

Shop Related Web Service Functions

CheckAccount()

CreateShopOrder()

CheckUserExists()

CheckPreviewExists()

ChangeCustomerPassword()

ChangeCustomerEmail()

PrepareLoginEx()

GetProjects()

GetLicenses()

GetThemes()

GetTrailer()

User data changes syncback

About Us

EULA

Search the site