This page explains the basics for using IMVU Monetization, where users can buy from your application using IMVU credits.
For coding details, please view the InAppPurchase demo and the API documentation shipped with the IMVUnity package.
- In order to create In-App Purchases (IAPs) your developer account must be signed up as an IMVU creator, with VIP access and in good standing.
- Be sure to verify your email address after you sign-up for the creator program.
- Set up your payout options. This defaults to 50% money and 50% credits, which you may want to change.
- In order to obtain your money you need to eventually fill out financial info, which is explained in the creator program.
- Create IAPs on your app's page https://secure.imvu.com/next/developer/app-xxx/ and set them to In-Test or Live
- For each platform remember to turn on the Approved Access permission for In-app Purchases
- Display a dialog in your game to let your user choose the IAP they want to purchase
- Call IMVU with the purchase request. This will trigger the display of a confirmation page where the user can authorize the transfer of their IMVU credits to your developer account.
- If the purchase is authorized by the user then your app must inform IMVU when the purchase has been fulfilled from your side. This moves the transaction into the Fulfilled state. (Note: Below is a command line tool in Python and PHP that shows you how to do this.)
IN-APP PURCHASE STATES
IAPs have three states:
- Draft: this IAP is not live and will not be seen by any customers
- In-Test: this IAP can only be made visible to registered testers of your app
- Live: this IAP can be made visible to all customers of your app
STAGES OF A PURCHASE TRANSACTION
The "transaction" that represents an IAP can have the following states:
- Created: The transaction has been created and IMVU knows about it and is waiting for the user to accept or reject the transaction (if the user has not made a decision within 5 minutes the transaction will automatically be changed to unauthorized.) A transaction in this state cannot be purchased by the same user until is has moved out of this state.
- Unauthorized: This transaction was not authorized by the user because it timed out, or the user specifically canceled the purchase. This transaction is now dead. The user can attempt to purchase the item again.
- Authorized: The user has confirmed with IMVU that they want to make this purchase. IMVU credits have been transferred from their account to the app developer's account. It is now up to the app developer to fulfill the purchase. A transaction in this state cannot be purchased by the same user until is has moved out of this state.
- Fulfilled: This transaction is complete. IMVU credits have been transferred and the developer has confirmed that the user was given what they paid for.
- Unfulfilled: The user authorized the transaction, but the developer failed to confirm that the user was given what they paid for. If a transaction is left in an authorized state for 13 days then it will be moved into the Unfulfilled state and the user and the IMVU credits from the transaction will be moved back from the app developer to the user.
- Reversed: This state is similar to the Unfulfilled state, except the transaction was reversed through manual intervention by an IMVU support agent. (Typically if the user has contacted support and complained about the purchase.)
- Failed: The user authorized the transaction, but the transaction failed to complete for some reason.
- The In-App Purchase demo shows a list of the currently purchasable IAPs.
- Pressing Buy starts the IMVU authorization flow where the user can confirm that they want to transfer their credits to the game developer. See the Buy method in the InApp Purchase demo, IapDetailUI.cs.
- When the user chooses BUY FOR @220 the credits are authorized and transferred. It is now up to the app developer to give the user what they paid for and mark the transaction as Fulfilled, so that IMVU knows the entire process is complete. (This is how we deal with networking inherent with the internet. If connectivity is lost between when the transaction is authorized and the app finds out about it, the application can query to see if there are any pending transactions in the Authorized state.
- The list on the right side of the In-App Purchase demo shows a list of transactions for the currently logged in user, along with the state of those transactions.
REQUIREMENTS OF YOUR APP
- Each time a user opens your app you should query to see if the user has any transactions pending in the authorized state. For each authorized transaction, ensure the user has been given the item he/she paid for and Fulfill the transaction with IMVU. Your app will need to make a request to your servers and the servers will need to make a server to server call to fulfill the transaction with IMVU. (Details below.)
- If the user has Reversed transactions that you have not previously reversed on your side then you may wish to take away the purchased item from the user. (For instance, if they purchased the +3 sword of smiting, then you may want to update your servers to take that item away from them...just be sure they have not since purchased that item again.)
Server Side IAP Fulfillment
- When an IAP is purchased your server is expected to provide the user with the goods they purchased, then let IMVU know that this step has been taken. At this point the transaction can be marked as fulfilled, which means it is complete.
- The provided python fulfillment script, or this PHP tool, contains details for how to make a server to server call to fulfill a transaction. This call should only be made from your server to IMVU servers, to prevent fraud. (Running the tool manually to test the IAP demo is fine too.)
- NOTE: This is basic HMAC authentication
Manual Server Side IAP Fulfillment (for use with IAP demo app only)
When testing with the InAppPurchases demo that is provided as part of the IMVUnity package, it is useful to be able to manually fulfill a transaction. This manual fulfillment can be accomplished with the following steps:
- Get your App Secret that is on your App Info page on the developer pages. (This value should never be shared, put into client code or checked into code in plain text. Treat like a password.)
- Get your App ID from the app that performed the purchase (This value is on your apps developer page AND is the same value you put in your IMVU Settings dialog for the platform you are currently using.)
- Get the app purchase url that represents the transaction you wish to fulfill (Example: https://api.imvu.com/app_purchase/app_purchase-1)
- You can view your IAP sales through the IMVU creator program dashboard (http://www.imvu.com/creators/creator_dashboard.php)
- You can load a list of IAPs that are active for your game
- You can load a list of transactions for the currently logged in IMVU user
- This list can be used to parse what has previously been purchased by a given user, but we suggest you also store purchase history on your servers where you will want to track game status per user
- Your app should check this list of transactions, any that are in the AUTHORIZED state should be FULFILLED at your servers
- VIP customers will automatically receive a 5% discount on all IAP purchases (this is be reflected in the item's price)
- A demo is provided to display and demonstrate how IAPs work (IMVUnity->Demos->InAppPurchases)
CAVEATS, LIMITATIONS AND KNOWN ISSUES
- If a user does not have enough credits to buy an IAP they will be presented with the option of buying credits on WebGL or Android apps. This option will not be available on iOS at this time.
- If you purchase IAPs as the developer of the APP those purchases will go through successfully, but you will not be charged IMVU credits and the transaction will not appear on the creator dashboard. This feature simplifies testing.
- Moving an IAP back to draft after it has been sold will throw an error in the IAP demo and will hide the purchase transactions for that IAP. For now we suggest you do not move an IAP back to the Draft state once a purchase of that IAP has been made.
- NOTE: minor API changes are likely to be required in future builds