Export (0) Print
Expand All

App License Schema

apps for Office and SharePoint

Learn about the elements and attributes of the app license schema, which defines the string that specifies validity and usage properties in app licenses.

Last modified: March 13, 2014

Applies to: Office 2013 | Project 2013 | SharePoint Foundation 2013 | SharePoint Server 2013

The following app license schema defines the structure that specifies usage properties in app licenses. If your app includes license validation checks, use this schema to create test licenses to test the license validation code in your app. For more information, see How to: Add license checks to your apps for Office and How to: Add license checks to your app for SharePoint.

Use the VerifyEntitlementToken method of the Office Store verification web service to determine if an app license is valid. The VerifyEntitlementToken method takes a app license token as a parameter, and returns an VerifyEntitlementTokenResponse that contains the license token properties, including whether or not the license token is valid.

To support app license testing, the Office Store verification web service does not validate the encryption token or any of the attribute values of license tokens where the test attribute is set to true. However, the service does interpret the token, and all the properties of the VerifyEntitlementTokenResponse object returned by the service can be read.

<r>
  <t 
    aid="{2[A-Z] 8-12[0-9]}" 
    pid="{GUID}" | "string" 
    cid="{16[0-H]}" 
    did="{GUID}" 
    ts="Integer" 
    et="Free" |"Trial" | "Paid"
    sl="true | 1" | "false| 0"
    ad="UTC" 
    ed="UTC" 
    sd="UTC" 
    te="UTC" 
    test="true | 1" | "false | 0"
    ss="0" | "1" | "2" | "3" | "4" />
  <d>VNNAnf36IrkyUVZlihQJNdUUZl/YFEfJOeldWBtd3IM=</d>
</r>

Elements

r

Required. The root element.

t

Required. Contains attributes that represent various properties of the app license.

Attributes

Attribute

Description

aid

Required text. The asset ID assigned to this app by the Office Store.

pid

Required text. The GUID that represents the product ID of the app.

The product ID of the app is specified in the app manifest.

cid

Required text. Represents the purchaser ID. This is an encrypted value of the Microsoft account used by the purchaser of the app.

did

For content and task pane apps for Office:

This attribute does not apply to content and task pane apps for Office.

For mail apps for Office:

String that represents the deployment ID of the Exchange deployment to which this app license applies. This value should be set to the primary authoritative domain for the Exchange deployment.

For apps for SharePoint:

GUID that represents the deployment ID of the SharePoint deployment to which this app license applies.

For test licenses for apps for SharePoint, you don't need to specify the deployment ID in the app license XML. The ImportAppLicense method supplies the correct deployment ID to the license token XML.

ts

Integer representing the total number of users licensed to access this app, by this purchaser.

For apps that are site licensed, this value is 0.

This attribute does not apply to apps for Office.

et

Required text. Enumeration that represents the type of app license.

Valid values include Free, Paid, and Trial.

ad

Required text. UTC time-date stamp that represents the acquisition date for the app license.

sl

Boolean value that represents whether the app license is a site license.

For content and task pane apps for Office:

This attribute does not apply to content and task pane apps for Office.

For mail apps for Office:

This attribute is optional for app licenses that are not site licenses. This attribute is required to be equal to true if the mail app is site licensed.

For apps for SharePoint:

This attribute is optional for app licenses that are not site licenses.

ed

Optional text. UTC time-date stamp that represents the expiration date for the app license.

This value can be used to check if the trial license is expired.

sd

Required text. UTC time-date stamp that represents one of the following:

  • The initial purchase of the license.

  • The latest manual license recovery time, if the purchaser has performed such a recovery using their Microsoft account.

te

Required text. UTC time-date stamp that represents the date the current app license token expires.

test

Optional Boolean value. Represents whether the app license is a test license.

ss

Optional integer. Represents the subscription status of the app license. This attribute is optional for apps that are not being sold as subscriptions.

This attribute accepts integers from 0 through 4. Valid values include:

Integer

Description

0

NotApplicable

The app license is not for a subscription app.

1

Active

The app license subscription is currently paid for.

Recommended user experience:

Full app experience.

2

FailedPayment

The automatic monthly billing for the app license subscription has failed.

There are several reasons payment may have failed. For example, the credit card being billed might have expired. When payment fails, emails are sent to the Microsoft account paying for the app license. However, the user might not check their Microsoft account email on a frequent basis, or, in the case of apps for SharePoint, the person paying for the app license may not actually be the person using the app license.

Recommended user experience:

Present UI in your app alerting the user of the problem with billing, so that they can resolve it.

3

Canceled

The app license subscription has been canceled, and final monthly billing period the user has paid for has expired.

Recommended user experience:

Present the user with information that their subscription has been cancelled. Provide information about your app, along with a hyperlink to your app’s Office Store listing page, so they are encouraged to renew their subscription.

4

DelayedCancel

The app license subscription has been canceled, but the subscription is still within the current, monthly billing period the user has paid for. Once the current, paid monthly billing period expires, the subscription status changes to Canceled.

Recommended user experience:

Full app experience. Additionally, you may want to present contextual UI to ask the user for feedback on why they are canceling their subscription, or to enourage them to re-subscribe.

d

Required. Encryption token used by the Office Store verification service to determine whether the app license token is valid. This is an encrypted signature derived from the literal string contained in the <t> element.

When you submit a test app license token to the Office Store verification web service, the service does not perform that validation check of comparing the encrypted signature in the <d> element to the string contained in the <t> element.

Remarks

Important noteImportant

When your app receives an app license token from its hosting environment, be it an Office application or SharePoint, developers are advised not to parse or otherwise manipulate the app license token string before passing it to the Office Store verification web service for verification. While the app license token is structured as an XML fragment, for purposes of validation the Office Store verification web service treats the token as a literal string. The Office Store verification web service compares the contents of the <t> element to the value of the <d> element, which is an encrypted signature derived from the literal string contained in the <t> element. Any reformatting of the license token, such as adding white space, tabs, line breaks, etc., will change the literal value of the <t> element and therefore cause the license verification check to fail.

When you submit a test app license token to the Office Store verification web service, the service does not perform that validation check of comparing the encrypted signature in the <d> element to the string contained in the <t> element. This enables developers to create their own test app license tokens for testing purposes without worrying about formatting, or generating the encryption signature for the <d> element.

Code example: App license XML for an app for SharePoint

The following example is the app license XML for an app for SharePoint, representing a trial app for which the purchaser has acquired 30 seats.

<r>
  <t 
    aid="WA900006056" 
    pid="{4FB601F2-5469-4542-B9FC-B96345DC8B39}" 
    cid="32F3E7FC559F4F49" 
    did="{0672BAE9-B41B-48FE-87F1-7F4D3DD3F3B1}" 
    ts="30" 
    et="Trial" 
    ad="2012-01-12T21:58:13Z" 
    ed="2012-06-30T21:58:13Z" 
    sd="2012-01-12T00:00:00Z" 
    te="2012-06-30T02:49:34Z" />
  <d>VNNAnf36IrkyUVZlihQJNdUUZl/YFEfJOeldWBtd3IM=</d>
</r>

Community Additions

ADD
Show:
© 2014 Microsoft