BLRInAppPurchase  1.0.0
BLRInAppPurchase.h File Reference
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>

Go to the source code of this file.

Typedefs

Public (opaque) object types.

These are object types you will use in the API.

typedef struct BIAP_AppStore BIAP_AppStore
 
typedef struct BIAP_ProductResponseData BIAP_ProductResponseData
 
typedef struct BIAP_TransactionResponseData BIAP_TransactionResponseData
 
typedef struct BIAP_Product BIAP_Product
 

Functions

Setup/Initialization Functions

These functions setup and create your app store connection.

void BIAP_RegisterKey (enum BIAP_StoreName store_name, const char *the_key)
 Allows you to register your public key for the app stores that require it. More...
 
void BIAP_Init (void)
 Initializes the library. More...
 
bool BIAP_IsInit (void)
 Has the library been initialized? More...
 
void BIAP_Quit (void)
 Shuts down the library. More...
 
struct BIAP_AppStoreBIAP_CreateAppStore (enum BIAP_StoreName store_name, void *native_platform_context, BIAP_ProductResponse product_response_callback, BIAP_TransactionResponse transaction_response_callback, void *user_data)
 Creates and starts a connection to the app store. More...
 
void BIAP_StartAppStore (struct BIAP_AppStore *app_store)
 Starts the app store. More...
 
void BIAP_FreeAppStore (struct BIAP_AppStore *app_store)
 Disconnects and frees your app store instance. More...
 
Core Workflow Functions

These functions are the core/primary functions to interact with the app store.

enum BIAP_StoreName BIAP_GetAppStoreName (struct BIAP_AppStore *app_store)
 Gets the name of the app store you are connected with. More...
 
void BIAP_RequestProducts (struct BIAP_AppStore *app_store, const char *nonconsumable_product_identifier_list[], size_t num_nonconsumables, const char *consumable_product_identifier_list[], size_t num_consumables, const char *subscription_product_identifier_list[], size_t num_subscriptions)
 Requests product information from your connected app store. More...
 
void BIAP_PurchaseProduct (struct BIAP_ProductResponseData *callback_data, struct BIAP_Product *the_product)
 Purchases the specified product from the app store. More...
 
void BIAP_FinishTransaction (struct BIAP_TransactionResponseData *callback_data)
 For those that require it, notifies the app store that the transaction is finished. More...
 
void BIAP_ConsumePurchase (struct BIAP_TransactionResponseData *callback_data_of_purchase)
 Consumes a consumable purchased product. More...
 
void BIAP_RestorePurchases (struct BIAP_AppStore *app_store)
 Requests all purchases a user has bought from the app store. More...
 
Functions for getting Product Properties

These functions return the product properties contained inside a BIAP_ProductResponseData during your product callbacks.

Warning
To prevent you from more memory management, all BIAP_GetProduct* property APIs that return pointers are internal pointers from the BIAP_ProductResponseData object, so you must not free the BIAP_ProductResponseData object until after you are done using those pointers.
struct BIAP_AppStoreBIAP_GetProductAppStore (struct BIAP_ProductResponseData *callback_data)
 Gets the app store handle that this callback originated from. More...
 
enum BIAP_EventType BIAP_GetProductEventType (struct BIAP_ProductResponseData *callback_data)
 Gets the BIAP_EventType associated with this callback data. More...
 
const char * BIAP_GetProductErrorString (struct BIAP_ProductResponseData *callback_data)
 Gets the error string associated with this callback data. More...
 
size_t BIAP_GetProductsListCount (struct BIAP_ProductResponseData *callback_data)
 Gets the number of valid products returned from your product request. More...
 
struct BIAP_ProductBIAP_GetProductInList (struct BIAP_ProductResponseData *callback_data, size_t list_index)
 Gets a valid product from a list of valid products returned from your product request. More...
 
struct BIAP_ProductBIAP_GetProductWithIdentifier (struct BIAP_ProductResponseData *callback_data, const char *product_identifer)
 Searches and returns a valid product from a list of valid products returned from your product request by the product identifier you specify. More...
 
const char * BIAP_GetProductTitle (struct BIAP_ProductResponseData *callback_data, struct BIAP_Product *product_object)
 Gets the product title string for the specified product. More...
 
const char * BIAP_GetProductDescription (struct BIAP_ProductResponseData *callback_data, struct BIAP_Product *product_object)
 Gets the product description string for the specified product. More...
 
const char * BIAP_GetProductIdentifier (struct BIAP_ProductResponseData *callback_data, struct BIAP_Product *product_object)
 Gets the product identifier string associated with this product. More...
 
const char * BIAP_GetProductLocalizedPrice (struct BIAP_ProductResponseData *callback_data, struct BIAP_Product *product_object)
 Gets the product localized price string for the specified product. More...
 
size_t BIAP_GetInvalidProductsListCount (struct BIAP_ProductResponseData *callback_data)
 Gets the number of invalid products returned from your product request. More...
 
const char * BIAP_GetInvalidProductIdentifier (struct BIAP_ProductResponseData *callback_data, size_t list_index)
 Gets a invalid product from a list of invalid products returned from your product request. More...
 
Functions for getting Transaction Properties

These functions return the transaction properties contained inside a BIAP_TransactionResponseData during your transaction callbacks.

Warning
To prevent you from more memory management, all BIAP_GetTransaction* property APIs that return pointers are internal pointers from the BIAP_TransactionResponseData object, so you must not free the BIAP_TransactionResponseData object until after you are done using those pointers.
struct BIAP_AppStoreBIAP_GetTransactionAppStore (struct BIAP_TransactionResponseData *callback_data)
 Gets the app store handle that this callback originated from. More...
 
enum BIAP_EventType BIAP_GetTransactionEventType (struct BIAP_TransactionResponseData *callback_data)
 Gets the BIAP_EventType associated with this callback data. More...
 
const char * BIAP_GetTransactionErrorString (struct BIAP_TransactionResponseData *callback_data)
 Gets the error string associated with this callback data. More...
 
enum BIAP_FailedTransactionType BIAP_GetTransactionErrorType (struct BIAP_TransactionResponseData *callback_data)
 Gets the BIAP_FailedTransactionType associated with this callback data. More...
 
const char * BIAP_GetTransactionProductIdentifier (struct BIAP_TransactionResponseData *callback_data)
 Gets the product identifier string associated with this callback data. More...
 
long long BIAP_GetTransactionPurchaseTime (struct BIAP_TransactionResponseData *callback_data)
 Gets the transaction purchase time in milliseconds since Epoch (Unix 1970). More...
 
long long BIAP_GetTransactionOriginalPurchaseTime (struct BIAP_TransactionResponseData *callback_data)
 (Android-only) Gets the original transaction purchase time in milliseconds since Epoch (Unix 1970). More...
 
const char * BIAP_GetTransactionOriginalJson (struct BIAP_TransactionResponseData *callback_data)
 (Android-only) Gets the JSON formatted receipt for a transaction. More...
 
(Apple) Receipt APIs

These functions allow you to interact with Apple's receipt system.

They are safe to call on Android, but will not have any useful effect.

void BIAP_RequestReceiptRefresh (struct BIAP_AppStore *app_store)
 (Apple-only) Refreshes the user's purchases receipt on the file system. More...
 
const char * BIAP_GetReceiptPath (struct BIAP_AppStore *app_store)
 (Apple-only) Gets the path to the receipt on the file system. More...
 
Debugging APIs

These functions are releated to debugging.

void BIAP_SetDebugLogging (bool should_enable)
 Enables extra debug log messages in the library. More...
 
bool BIAP_IsDebugLogging (void)
 Returns whether debug logging is enabled. More...
 
Platform Specific APIs

These functions are special platform specific APIs that only exist on specific platforms.

bool BIAP_Android_HandleOnActivityResult (void *jni_env, void *original_activity, int32_t request_code, int32_t result_code, void *intent_data)
 (Android-only) Call this function in your Android Activity's onActivityResult method. More...
 

Store Name constants

These are constants you should use to distinguish between the different stores.

enum  BIAP_StoreName {
  BIAP_STORE_UNKNOWN = -2,
  BIAP_STORE_DEFAULT = -1,
  BIAP_STORE_NONE = 0,
  BIAP_STORE_APPLE,
  BIAP_STORE_GOOGLEPLAY,
  BIAP_STORE_AMAZON,
  BIAP_STORE_SAMSUNG,
  BIAP_STORE_NOKIA,
  BIAP_STORE_APPLAND,
  BIAP_STORE_APTOIDE,
  BIAP_STORE_APPMALL,
  BIAP_STORE_SLIDEME,
  BIAP_STORE_YANDEX,
  BIAP_STORE_FORTUMO,
  BIAP_STORE_SKUBIT,
  BIAP_STORE_SKUBITTEST,
  BIAP_STORE_WINDOWSSTORE
}
 
typedef enum BIAP_StoreName BIAP_StoreName
 

Callback Event Types

Each callback also provides you an BIAP_EventType so you can identify the purpose of the callback. And for failed transactions, you may also get the the BIAP_FailedTransactionType to identify a more specific reason for the failure.

enum  BIAP_EventType {
  BIAP_EVENT_UNKNOWN = 0,
  BIAP_EVENT_INIT_FAILED,
  BIAP_EVENT_INIT_FINISHED,
  BIAP_EVENT_REQUEST_FAILED,
  BIAP_EVENT_PRODUCT_REQUEST,
  BIAP_EVENT_TRANSACTION_FAILED,
  BIAP_EVENT_TRANSACTION_PURCHASING,
  BIAP_EVENT_TRANSACTION_PURCHASED,
  BIAP_EVENT_TRANSACTION_PURCHASE_CANCELLED,
  BIAP_EVENT_TRANSACTION_PURCHASE_REFUNDED,
  BIAP_EVENT_TRANSACTION_RESTORED,
  BIAP_EVENT_TRANSACTION_RESTORE_FINISHED,
  BIAP_EVENT_TRANSACTION_RESTORE_FAILED,
  BIAP_EVENT_TRANSACTION_DEFFERED,
  BIAP_EVENT_TRANSACTION_CONSUMED,
  BIAP_EVENT_TRANSACTION_CONSUMED_FAILED,
  BIAP_EVENT_TRANSACTION_RECEIPT_REQUEST_FINISHED,
  BIAP_EVENT_TRANSACTION_RECEIPT_REQUEST_FAILED
}
 These event types are given to you for every callback so you distingush the purpose of the event. More...
 
enum  BIAP_FailedTransactionType {
  BIAP_FAILED_TRANSACTION_NONE = -1,
  BIAP_FAILED_TRANSACTION_OTHER_ERROR = 0,
  BIAP_FAILED_TRANSACTION_USER_CANCELLED,
  BIAP_FAILED_TRANSACTION_PAYMENT_INVALID,
  BIAP_FAILED_TRANSACTION_PAYMENT_NOT_ALLOWED,
  BIAP_FAILED_TRANSACTION_CLIENT_INVALID,
  BIAP_FAILED_TRANSACTION_BILLING_UNAVAILABLE,
  BIAP_FAILED_TRANSACTION_ITEM_UNAVAILABLE,
  BIAP_FAILED_TRANSACTION_ITEM_ALREADY_OWNED,
  BIAP_FAILED_TRANSACTION_DEVELOPER_ERROR,
  BIAP_FAILED_TRANSACTION_NOT_SUPPORTED
}
 For an error in a transaction event, this sub-type can help you determine the reason for the failure. More...
 
typedef enum BIAP_EventType BIAP_EventType
 
typedef enum BIAP_FailedTransactionType BIAP_FailedTransactionType
 

Callback Functions

There are two callback functions you must provide. One is for receiving product information. The other is for all other (transaction) information.

typedef void(* BIAP_ProductResponse) (enum BIAP_EventType callback_type, struct BIAP_ProductResponseData *callback_data, void *user_data)
 This is the function signature for your Product callbacks. More...
 
typedef void(* BIAP_TransactionResponse) (enum BIAP_EventType callback_type, struct BIAP_TransactionResponseData *callback_data, void *user_data)
 This is the function signature for your Transaction callbacks. More...
 
void BIAP_FreeProductResponseData (struct BIAP_ProductResponseData *callback_data)
 Frees the memory for the BIAP_ProductResponseData that was created for you in the Product callback. More...
 
void BIAP_FreeTransactionResponseData (struct BIAP_TransactionResponseData *callback_data)
 Frees the memory for the BIAP_TransactionResponseData that was created for you in the Transaction callback. More...
 

Typedef Documentation

◆ BIAP_AppStore

typedef struct BIAP_AppStore BIAP_AppStore

◆ BIAP_EventType

◆ BIAP_FailedTransactionType

◆ BIAP_Product

typedef struct BIAP_Product BIAP_Product

◆ BIAP_ProductResponse

typedef void(* BIAP_ProductResponse) (enum BIAP_EventType callback_type, struct BIAP_ProductResponseData *callback_data, void *user_data)

This is the function signature for your Product callbacks.

This is the function signature for your Product callbacks. The function you create must be passed to BIAP_CreateAppStore and all product callbacks will be sent to your function.

Parameters
callback_typeThis tells you the status of your network request, typically BIAP_EVENT_PRODUCT_REQUEST or BIAP_EVENT_REQUEST_FAILED.
callback_dataThis contains all the data sent to you from your product request. Use the BIAP_GetProduct* functions on this object to pull out the proerties you want. You must free this object with BIAP_FreeProductResponseData when you are done with it.
user_dataThis is the same pointer you passed as user data when you called BIAP_CreateAppStore.
Warning
Every callback invocation creates a new BIAP_ProductResponseData object. You are required to free these objects when you are done with them by calling BIAP_FreeProductResponseData. To prevent you from more memory management, all BIAP_GetProduct* property APIs that return pointers, return internal pointers from the BIAP_ProductResponseData object, so you must not free the object until after you are done with all those pointers.
See also
BIAP_CreateAppStore BIAP_FreeProductResponseData and the BIAP_GetProduct* family of functions.

◆ BIAP_ProductResponseData

◆ BIAP_StoreName

◆ BIAP_TransactionResponse

typedef void(* BIAP_TransactionResponse) (enum BIAP_EventType callback_type, struct BIAP_TransactionResponseData *callback_data, void *user_data)

This is the function signature for your Transaction callbacks.

This is the function signature for your Transaction callbacks. This is the catch all for all callbacks not in the Product callback category. The function you create must be passed to BIAP_CreateAppStore and all product callbacks will be sent to your function.

Parameters
callback_typeThis tells you the status of your network request.
callback_dataThis contains all the data sent to you from your product request. Use the BIAP_GetTransaction* functions on this object to pull out the proerties you want. You must free this object with BIAP_FreeTransactionResponseData when you are done with it.
user_dataThis is the same pointer you passed as user data when you called BIAP_CreateAppStore.
Warning
Every callback invocation creates a new BIAP_TransactionResponse object. You are required to free these objects when you are done with them by calling BIAP_FreeTransactionResponseData. To prevent you from more memory management, all BIAP_GetTransaction* property APIs that return pointers, return internal pointers from the BIAP_TransactionResponseData object, so you must not free the object until after you are done with all those pointers.
See also
BIAP_CreateAppStore BIAP_FreeTransactionResponseData and the BIAP_GetTransaction* family of functions.

◆ BIAP_TransactionResponseData

Enumeration Type Documentation

◆ BIAP_EventType

These event types are given to you for every callback so you distingush the purpose of the event.

Enumerator
BIAP_EVENT_UNKNOWN 

products & transactions

BIAP_EVENT_INIT_FAILED 

transaction

BIAP_EVENT_INIT_FINISHED 

transaction

BIAP_EVENT_REQUEST_FAILED 

products & transactions

BIAP_EVENT_PRODUCT_REQUEST 

products

BIAP_EVENT_TRANSACTION_FAILED 

transaction

BIAP_EVENT_TRANSACTION_PURCHASING 

transaction, Apple-only

BIAP_EVENT_TRANSACTION_PURCHASED 

transaction

BIAP_EVENT_TRANSACTION_PURCHASE_CANCELLED 

transaction, Android-only

BIAP_EVENT_TRANSACTION_PURCHASE_REFUNDED 

transaction, Android-only

BIAP_EVENT_TRANSACTION_RESTORED 

transaction

BIAP_EVENT_TRANSACTION_RESTORE_FINISHED 

transaction

BIAP_EVENT_TRANSACTION_RESTORE_FAILED 

transaction

BIAP_EVENT_TRANSACTION_DEFFERED 

transaction, Apple-only

BIAP_EVENT_TRANSACTION_CONSUMED 

transaction

BIAP_EVENT_TRANSACTION_CONSUMED_FAILED 

transaction

BIAP_EVENT_TRANSACTION_RECEIPT_REQUEST_FINISHED 

transaction

BIAP_EVENT_TRANSACTION_RECEIPT_REQUEST_FAILED 

transaction

◆ BIAP_FailedTransactionType

For an error in a transaction event, this sub-type can help you determine the reason for the failure.

Enumerator
BIAP_FAILED_TRANSACTION_NONE 
BIAP_FAILED_TRANSACTION_OTHER_ERROR 
BIAP_FAILED_TRANSACTION_USER_CANCELLED 
BIAP_FAILED_TRANSACTION_PAYMENT_INVALID 

Apple.

BIAP_FAILED_TRANSACTION_PAYMENT_NOT_ALLOWED 

Apple.

BIAP_FAILED_TRANSACTION_CLIENT_INVALID 

Apple.

BIAP_FAILED_TRANSACTION_BILLING_UNAVAILABLE 

Android.

BIAP_FAILED_TRANSACTION_ITEM_UNAVAILABLE 

Android.

BIAP_FAILED_TRANSACTION_ITEM_ALREADY_OWNED 

Android.

BIAP_FAILED_TRANSACTION_DEVELOPER_ERROR 

Android.

BIAP_FAILED_TRANSACTION_NOT_SUPPORTED 

ex: calling RefreshReceipt on Android

◆ BIAP_StoreName

Enumerator
BIAP_STORE_UNKNOWN 
BIAP_STORE_DEFAULT 
BIAP_STORE_NONE 
BIAP_STORE_APPLE 
BIAP_STORE_GOOGLEPLAY 
BIAP_STORE_AMAZON 
BIAP_STORE_SAMSUNG 
BIAP_STORE_NOKIA 
BIAP_STORE_APPLAND 
BIAP_STORE_APTOIDE 
BIAP_STORE_APPMALL 
BIAP_STORE_SLIDEME 
BIAP_STORE_YANDEX 
BIAP_STORE_FORTUMO 
BIAP_STORE_SKUBIT 
BIAP_STORE_SKUBITTEST 
BIAP_STORE_WINDOWSSTORE 

Function Documentation

◆ BIAP_Android_HandleOnActivityResult()

bool BIAP_Android_HandleOnActivityResult ( void *  jni_env,
void *  original_activity,
int32_t  request_code,
int32_t  result_code,
void *  intent_data 
)

(Android-only) Call this function in your Android Activity's onActivityResult method.

Call this function in your Android Activity's onActivityResult method.

Parameters
jni_envThe JNIEnv* you need to work with your JNI environment. (This was casted to void* to avoid needing the jni.h header which pollutes the namespace and sometimes causes problems.)
original_activityThe Activity you are using to manage the store. This is expected to be the same activity you passed to BIAP_CreateAppStore. (This was casted to void* to avoid needing the jni.h header which pollutes the namespace and sometimes causes problems.)
request_codeThe request_code you get from your Activity's onActivityResult callback.
result_codeThe result_code you get from your Activity's onActivityResult callback.
intent_dataThe intent_data you get from your Activity's onActivityResult callback. (This was casted to void* to avoid needing the jni.h header which pollutes the namespace and sometimes causes problems.)
Returns
Returns true if the underlying implemention (OpenIAB) handled the result, false otherwise.
Note
For those working directly in Java, as a convenience, instead of directly calling this C function, you may call this Java method: public static boolean com.blurrrsdk.blrinapppurchase.BLRInterfaceHelper.handleActivityResult(Activity original_activity, int request_code, int result_code, Intent intent_data).
This function only exists on Android and is not callable on other platforms.

◆ BIAP_ConsumePurchase()

void BIAP_ConsumePurchase ( struct BIAP_TransactionResponseData callback_data_of_purchase)

Consumes a consumable purchased product.

For app stores that track consumable status, this will send a request/notification to the app store that the product will be consumed.

Parameters
callback_data_of_purchaseThis is the callback data containing the purchase of the product the user wishes to consume. You may get this object from either the original BIAP_PurchaseProduct/BIAP_EVENT_TRANSACTION_PURCHASED callback or from calling BIAP_RestorePurchases/BIAP_EVENT_TRANSACTION_RESTORED callback.
Note
Stores like Google Play require you to use this API for consumables because they will not allow users to purchase the item again until it has been consumed.
Be advised that because this is a network request, there may be a considerable delay between your request time and server acknowledgement. Factor this into how you allow users to consume their consumables.
Apple does not track consumables and thus does not have a native API for this. As a convenience, BLRInAppPurchase generates a fake successful BIAP_EVENT_TRANSACTION_CONSUMED event.
See also
BIAP_PurchaseProduct BIAP_RestorePurchases

◆ BIAP_CreateAppStore()

struct BIAP_AppStore* BIAP_CreateAppStore ( enum BIAP_StoreName  store_name,
void *  native_platform_context,
BIAP_ProductResponse  product_response_callback,
BIAP_TransactionResponse  transaction_response_callback,
void *  user_data 
)

Creates and starts a connection to the app store.

Creates and starts a connection to the app store and returns an instance to the handle.

Parameters
store_nameReserved for future use. For now, pass BIAP_STORE_DEFAULT. It will autodetect the store the use. On Apple, it uses the Apple store. On Android, autodetection looks at how the app was installed and what permissions are set.
native_platform_contextFor Android, you must pass the JNI jobject of the Activity instance that will display your store. SDL users: use SDL_AndroidGetActivity(). Other platforms may pass NULL.
product_response_callbackThe function pointer to your function for handling product callbacks.
transaction_response_callbackThe function pointer to your function for handling all other callbacks besides products.
user_dataAny pointer you pass here will be passed back to you during a callback.
Returns
Returns a handle for the store you created.
Note
Call BIAP_StartAppStore after this to get things going.
Most use cases only ever need to create one store instance. However, it is possible to create multiple store instances. For example one potential use case is that since Android Activities are isolated and hard to coordinate data with the rest of your app, you could have difference instances for different activities. However, it is not advised to try to keep multiple store instances simultaneously running.
See also
BIAP_FreeAppStore BIAP_StartAppStore BIAP_GetAppStoreName

◆ BIAP_FinishTransaction()

void BIAP_FinishTransaction ( struct BIAP_TransactionResponseData callback_data)

For those that require it, notifies the app store that the transaction is finished.

For those that require it, notifies the app store that the transaction is finished. You must call this following every successful transaction, otherwise Apple will assume the transaction was interrupted and will attempt to resume in the future, such as the next application launch. If you are offering the item as downloadable content, do not call this function until after the download is complete.

Parameters
callback_dataThe transaction you were handed in your BIAP_TransactionResponse callback which you want to declare as finished.
Note
Apple requires this, but Android stores do not have an API like this. However as a convenince, it is safe to call this on Android so you can keep your code the same for all platforms.
See also
BIAP_PurchaseProduct

◆ BIAP_FreeAppStore()

void BIAP_FreeAppStore ( struct BIAP_AppStore app_store)

Disconnects and frees your app store instance.

Disconnects and frees your app store instance.

Parameters
app_storeThe app store instance you want to free.

◆ BIAP_FreeProductResponseData()

void BIAP_FreeProductResponseData ( struct BIAP_ProductResponseData callback_data)

Frees the memory for the BIAP_ProductResponseData that was created for you in the Product callback.

Frees the memory for the BIAP_ProductResponseData that was created for you in the Product callback.

Parameters
callback_dataThe data created for you in a callback which you want to free.

◆ BIAP_FreeTransactionResponseData()

void BIAP_FreeTransactionResponseData ( struct BIAP_TransactionResponseData callback_data)

Frees the memory for the BIAP_TransactionResponseData that was created for you in the Transaction callback.

Frees the memory for the BIAP_TransactionResponseData that was created for you in the Transaction callback.

Parameters
callback_dataThe data created for you in a callback which you want to free.

◆ BIAP_GetAppStoreName()

enum BIAP_StoreName BIAP_GetAppStoreName ( struct BIAP_AppStore app_store)

Gets the name of the app store you are connected with.

Gets the name of the app store you are connected with.

Returns
Returns the enum constant of the app store you are in use. When there is no store, it returns BIAP_STORE_NONE.
Warning
This is only guaranteed to return a valid store after the BIAP_EVENT_INIT_FINISHED callback event has happened. Otherwise the store may be BIAP_STORE_NONE.

◆ BIAP_GetInvalidProductIdentifier()

const char* BIAP_GetInvalidProductIdentifier ( struct BIAP_ProductResponseData callback_data,
size_t  list_index 
)

Gets a invalid product from a list of invalid products returned from your product request.

Gets a invalid product from a list of invalid products returned from your product request. Invalid products are products you requested in your product request, but do not exist on the server. The callback_data is a container that contains a list of all the products you requested. This function will let you retrieve a product by array index.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on.
list_indexThe index location of the invalid product string you want to retrieve. Array indices start counting at 0.
Returns
Returns a string to an invalid product or NULL if one doesn't exist at the specified location. Do not call free() on this returned value. It is an internal pointer to data contained in the callback_data. Do not free the callback_data until you are done with the product.
size_t number_of_invalid_products = BIAP_GetInvalidProductsListCount(callback_data);
for(size_t i=0; i<number_of_invalid_products; i++)
{
const char* invalid_product_identifier = BIAP_GetInvalidProductIdentifier(callback_data, i);
SDL_Log("Invalid Product Identifier: %s", invalid_product_identifier);
}
See also
BIAP_GetInvalidProductsListCount

◆ BIAP_GetInvalidProductsListCount()

size_t BIAP_GetInvalidProductsListCount ( struct BIAP_ProductResponseData callback_data)

Gets the number of invalid products returned from your product request.

Gets the number of invalid products returned from your product request. Invalid products are products you requested in your product request, but do not exist on the server. The callback_data is a container that contains all the products you requested. This function will tell you how many valid products are in there.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on.
Returns
Returns the number of valid products in the callback_data.
See also
BIAP_GetInvalidProductIdentifier to retrieve invalid products from the callback_data.

◆ BIAP_GetProductAppStore()

struct BIAP_AppStore* BIAP_GetProductAppStore ( struct BIAP_ProductResponseData callback_data)

Gets the app store handle that this callback originated from.

Gets the app store handle that this callback originated from.

Returns
The app store handle.

◆ BIAP_GetProductDescription()

const char* BIAP_GetProductDescription ( struct BIAP_ProductResponseData callback_data,
struct BIAP_Product product_object 
)

Gets the product description string for the specified product.

Gets the product description string for the specified product. This is information returned by the app store and may be localized.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on.
product_objectThe product you wish to operate on. It should have originated from the same callback_data you are passing.
Returns
Returns the description string. Do not call free() on this string. It is an internal pointer to data contained in the callback_data. Do not free the callback_data until you are done with the string or make your own copy of the string. Will always return an empty string instead of NULL.

◆ BIAP_GetProductErrorString()

const char* BIAP_GetProductErrorString ( struct BIAP_ProductResponseData callback_data)

Gets the error string associated with this callback data.

Gets the error string associated with this callback data in the case that the callback was for an error condition.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on.
Returns
Returns the error string. Do not call free() on this string. It is an internal pointer to data contained in the callback_data. Do not free the callback_data until you are done with the string or make your own copy of the string. Will always return an empty string instead of NULL.

◆ BIAP_GetProductEventType()

enum BIAP_EventType BIAP_GetProductEventType ( struct BIAP_ProductResponseData callback_data)

Gets the BIAP_EventType associated with this callback data.

Gets the BIAP_EventType associated with this callback data. This is the same value that was given to you in the callback event. This is provided as a convenience.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on.
Returns
Returns the event type associated with this callback data.

◆ BIAP_GetProductIdentifier()

const char* BIAP_GetProductIdentifier ( struct BIAP_ProductResponseData callback_data,
struct BIAP_Product product_object 
)

Gets the product identifier string associated with this product.

Gets the product identifier string associated with this product.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on.
product_objectThe product you wish to operate on. It should have originated from the same callback_data you are passing.
Returns
Returns the product identifier string. Do not call free() on this string. It is an internal pointer to data contained in the callback_data. Do not free the callback_data until you are done with the string or make your own copy of the string. Will always return an empty string instead of NULL.

◆ BIAP_GetProductInList()

struct BIAP_Product* BIAP_GetProductInList ( struct BIAP_ProductResponseData callback_data,
size_t  list_index 
)

Gets a valid product from a list of valid products returned from your product request.

Gets a valid product from a list of valid products returned from your product request. The callback_data is a container that contains a list of all the products you requested. This function will let you retrieve a product by array index.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on.
list_indexThe index location of the product you want to retrieve. Array indices start counting at 0.
Returns
Returns a pointer to a valid product or NULL if one doesn't exist at the specified location. Do not call free() on this returned value. It is an internal pointer to data contained in the callback_data. Do not free the callback_data until you are done with the product.
size_t number_of_valid_products = BIAP_GetProductsListCount(callback_data);
for(size_t i=0; i<number_of_valid_products; i++)
{
struct BIAP_Product* current_product = BIAP_GetProductInList(callback_data, i);
const char* product_identifier = BIAP_GetProductIdentifier(callback_data, current_product);
const char* product_title = BIAP_GetProductTitle(callback_data, current_product);
const char* product_description = BIAP_GetProductDescription(callback_data, current_product);
const char* localized_price = BIAP_GetLocalizedPrice(callback_data, current_product);
SDL_Log("Product Identifier: %s\n"
"Product Title: %s\n"
"Product Description: %s\n"
"Localized Price: %s\n",
product_identifier,
product_title,
product_description,
localized_price
);
}
See also
BIAP_GetProductsListCount

◆ BIAP_GetProductLocalizedPrice()

const char* BIAP_GetProductLocalizedPrice ( struct BIAP_ProductResponseData callback_data,
struct BIAP_Product product_object 
)

Gets the product localized price string for the specified product.

Gets the product localized price string for the specified product. This is information returned by the app store and will already have the correct price for the user's region. The string also is properly localized and contains the correct currency symbols and formatting, e.g. $0.99.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on.
product_objectThe product you wish to operate on. It should have originated from the same callback_data you are passing.
Returns
Returns the description string. Do not call free() on this string. It is an internal pointer to data contained in the callback_data. Do not free the callback_data until you are done with the string or make your own copy of the string. Will always return an empty string instead of NULL.

◆ BIAP_GetProductsListCount()

size_t BIAP_GetProductsListCount ( struct BIAP_ProductResponseData callback_data)

Gets the number of valid products returned from your product request.

Gets the number of valid products returned from your product request. The callback_data is a container that contains all the products you requested. This function will tell you how many valid products are in there.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on.
Returns
Returns the number of valid products in the callback_data.
See also
BIAP_GetProductInList or BIAP_GetProductWithIdentifier to retrieve products from the callback_data.

◆ BIAP_GetProductTitle()

const char* BIAP_GetProductTitle ( struct BIAP_ProductResponseData callback_data,
struct BIAP_Product product_object 
)

Gets the product title string for the specified product.

Gets the product title string for the specified product. This is information returned by the app store and may be localized.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on.
product_objectThe product you wish to operate on. It should have originated from the same callback_data you are passing.
Returns
Returns the title string. Do not call free() on this string. It is an internal pointer to data contained in the callback_data. Do not free the callback_data until you are done with the string or make your own copy of the string. Will always return an empty string instead of NULL.

◆ BIAP_GetProductWithIdentifier()

struct BIAP_Product* BIAP_GetProductWithIdentifier ( struct BIAP_ProductResponseData callback_data,
const char *  product_identifer 
)

Searches and returns a valid product from a list of valid products returned from your product request by the product identifier you specify.

Searches and returns a valid product from a list of valid products returned from your product request by the product identifier you specify. The callback_data is a container that contains a list of all the products you requested. This function will let you retrieve a product by the product identifier name.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on.
product_identiferThe product identifier of the product you want to retrieve.
Returns
Returns a pointer to a valid product or NULL if one doesn't exist at the specified location. Do not call free() on this returned value. It is an internal pointer to data contained in the callback_data. Do not free the callback_data until you are done with the product. Will always return an empty string instead of NULL.

◆ BIAP_GetReceiptPath()

const char* BIAP_GetReceiptPath ( struct BIAP_AppStore app_store)

(Apple-only) Gets the path to the receipt on the file system.

Gets the path to the receipt on the file system. Use BIAP_RequestReceiptRefresh to make sure the receipt exists and is up-to-date.

Parameters
app_storeThe app store handle you want to request from.
Returns
Returns an empty string if a receipt does not exist or a string containing the path to the receipt. Do not call free() on this string. Will always return an empty string instead of NULL.
Note
This is only useful for Apple platforms. You will get NULL on other platforms.
See also
BIAP_RequestReceiptRefresh BIAP_GetTransactionOriginalJson

◆ BIAP_GetTransactionAppStore()

struct BIAP_AppStore* BIAP_GetTransactionAppStore ( struct BIAP_TransactionResponseData callback_data)

Gets the app store handle that this callback originated from.

Gets the app store handle that this callback originated from.

Returns
The app store handle.

◆ BIAP_GetTransactionErrorString()

const char* BIAP_GetTransactionErrorString ( struct BIAP_TransactionResponseData callback_data)

Gets the error string associated with this callback data.

Gets the error string associated with this callback data in the case that the callback was for an error condition.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on.
Returns
Returns the error string. Do not call free() on this string. It is an internal pointer to data contained in the callback_data. Do not free the callback_data until you are done with the string or make your own copy of the string. Will always return an empty string instead of NULL.

◆ BIAP_GetTransactionErrorType()

enum BIAP_FailedTransactionType BIAP_GetTransactionErrorType ( struct BIAP_TransactionResponseData callback_data)

Gets the BIAP_FailedTransactionType associated with this callback data.

Gets the BIAP_FailedTransactionType associated with this callback data in the case that the callback was for an error condition.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on.
Returns
Returns the failure type associated with this callback data.

◆ BIAP_GetTransactionEventType()

enum BIAP_EventType BIAP_GetTransactionEventType ( struct BIAP_TransactionResponseData callback_data)

Gets the BIAP_EventType associated with this callback data.

Gets the BIAP_EventType associated with this callback data. This is the same value that was given to you in the callback event. This is provided as a convenience.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on.
Returns
Returns the event type associated with this callback data.

◆ BIAP_GetTransactionOriginalJson()

const char* BIAP_GetTransactionOriginalJson ( struct BIAP_TransactionResponseData callback_data)

(Android-only) Gets the JSON formatted receipt for a transaction.

(Android-only) Gets the JSON formatted receipt for a transaction.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on. This must be an object that was actually purchased, received with an event type of BIAP_EVENT_TRANSACTION_PURCHASED or BIAP_EVENT_TRANSACTION_RESTORED.
Returns
Returns the JSON formatted receipt string. Do not call free() on this string. It is an internal pointer to data contained in the callback_data. Do not free the callback_data until you are done with the string or make your own copy of the string. Will always return an empty string instead of NULL.
See also
BIAP_GetReceiptPath BIAP_RequestReceiptRefresh

◆ BIAP_GetTransactionOriginalPurchaseTime()

long long BIAP_GetTransactionOriginalPurchaseTime ( struct BIAP_TransactionResponseData callback_data)

(Android-only) Gets the original transaction purchase time in milliseconds since Epoch (Unix 1970).

(Android-only) Gets the original transaction purchase time in milliseconds since Epoch (Unix 1970).

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on. This must be an object that was actually purchased, received with an event type of BIAP_EVENT_TRANSACTION_PURCHASED or BIAP_EVENT_TRANSACTION_RESTORED.
Returns
The transaction purchase time in milliseconds since Epoch (Unix 1970). 0 if not available.

◆ BIAP_GetTransactionProductIdentifier()

const char* BIAP_GetTransactionProductIdentifier ( struct BIAP_TransactionResponseData callback_data)

Gets the product identifier string associated with this callback data.

Gets the product identifier string associated with this callback data.

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on.
Returns
Returns the product identifier string. Do not call free() on this string. It is an internal pointer to data contained in the callback_data. Do not free the callback_data until you are done with the string or make your own copy of the string. Will always return an empty string instead of NULL.

◆ BIAP_GetTransactionPurchaseTime()

long long BIAP_GetTransactionPurchaseTime ( struct BIAP_TransactionResponseData callback_data)

Gets the transaction purchase time in milliseconds since Epoch (Unix 1970).

Gets the transaction purchase time in milliseconds since Epoch (Unix 1970).

Parameters
callback_dataThe object containing all the data associated with a callback event you wish to operate on. This must be an object that was actually purchased, received with an event type of BIAP_EVENT_TRANSACTION_PURCHASED or BIAP_EVENT_TRANSACTION_RESTORED.
Returns
The transaction purchase time in milliseconds since Epoch (Unix 1970).

◆ BIAP_Init()

void BIAP_Init ( void  )

Initializes the library.

Initializes the library.

Warning
Please take care to not call multiple times without being paired with BIAP_Quit. Some platforms (notably Android) indiscriminately reset everything and may leak if BIAP_Quit is not used.
See also
BIAP_IsInit BIAP_Quit

◆ BIAP_IsDebugLogging()

bool BIAP_IsDebugLogging ( void  )

Returns whether debug logging is enabled.

Returns whether debug logging is enabled.

Returns
True if debug logging is enabled, false otherwise
See also
BIAP_SetDebugLogging

◆ BIAP_IsInit()

bool BIAP_IsInit ( void  )

Has the library been initialized?

Returns whether the library been initialized.

Returns
Returns true if initialized, false otherwise.
See also
BIAP_Init BIAP_Quit

◆ BIAP_PurchaseProduct()

void BIAP_PurchaseProduct ( struct BIAP_ProductResponseData callback_data,
struct BIAP_Product the_product 
)

Purchases the specified product from the app store.

Begins the sequence of events to allow the user to purchase an item from the app store. The results of the transaction will be returned in your BIAP_TransactionResponse callback. BIAP_EVENT_TRANSACTION_PURCHASED and BIAP_EVENT_TRANSACTION_FAILED are the two most important events to look for during this transaction. Other events may also trigger during this process depending on the app store in use.

Parameters
callback_dataThis is the callback data containing the product you want to purchase, which was originally handed to you during your BIAP_ProductResponse callback from calling BIAP_RequestProducts.
the_productThis is the specific product you want to purchase. This object was pulled out from the callback_data using BIAP_GetProductInList or BIAP_GetProductWithIdentifier.
Note
The InAppPurchase workflow is to always RequestProducts first. Then you use the object(s) returned from the callback(s) to pass as the parameter to BIAP_PurchaseProduct.
Apple requires that you notify the store when you have completed a transaction, otherwise Apple will keep re-attempting to redo the transaction. Call BIAP_FinishTransaction when you have completed the purchase. If your purchase involves external downloads, you should call finish only after the the download finishes.
See also
BIAP_RequestProducts BIAP_GetProductInList BIAP_GetProductWithIdentifier BIAP_FinishTransaction

◆ BIAP_Quit()

void BIAP_Quit ( void  )

Shuts down the library.

Shuts down the library.

Note
Particularly for Android, it is good to make sure to call this when your program quits/exits. This is useful in avoiding the NDK problems with global/static variables not being re-initialized on subsequent relaunches.
See also
BIAP_IsInit BIAP_Quit

◆ BIAP_RegisterKey()

void BIAP_RegisterKey ( enum BIAP_StoreName  store_name,
const char *  the_key 
)

Allows you to register your public key for the app stores that require it.

Allows you to register your public key for the app stores that require it. Google Play, Yandex, Appland, and SlideME require you to provide keys. You must register your keys before you call BIAP_CreateAppStore. If you are using a different app store, the keys you register will be ignored.

Parameters
store_nameUse the provided BIAP_STORE_* string constants to specify which store your key goes with.
the_keyYour public key.
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5F8fASyrDFdaXrkoW8kNtwH5JIkLnNuTD5uE1a37TbI5LDZR"
"VgvMIYAtZ9CAHAfLnJ6OEZt0lvLLJSKVuS47VqYVhGZciOkX8TEihONBRwis6i9A3JnKfyqm0iiT+P0CEktOLuFLROIo13"
"utCIO++6h7A7/WLfxNV+Jnxfs9OEHyyPS+MdHxa0wtZGeAGiaN65BymsBQo7J/ABt2DFyMJP1R/nJM45F8yu4D6wSkUNKz"
"s/QbPfvHJQzq56/B/hbx59EkzkInqC567hrlUlX4bU5IvOTF/B1G+UMuKg80m3I1IcQk4FD2D9oJ3E+8IXG/1UdejrOsmq"
"DAzE7LkMl8xwIDAQAB"
);
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAs4SI/obW+q3dhsY3g5B6UggPcL5olWK8WY3tnTa2k3i2U40j"
"QuHRNNs8SqzdJeuoBLsKjaEsdTT0SJtEucOMZrprXMch97QtuLB4Mgu3Gs7USL6dM7NCUSoYrgOgw1Koi+ab+ZvFJkVMb9"
"a2EjYzR3aP0k4xjKyG2gW1rIEMMepxHm22VFjEg6YxBy+ecwRrjqDJOAPJyH6uSl8vUT8AKuG+hcCuYbNvlMdEZJo6MXJ9"
"vPNf/qPHwMy5G+faEprL6zR+HaPfxEqN/d8rbrW0qnr8LpXJ+nPB3/irBiMSZSqA222GC7m12sNNmNnNNlI397F3fRQSTz"
"VSRZt14YdPzwIDAQAB"
);
"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC5idC9c24V7a7qCJu7kdIyOZsk\n"
"W0Rc7/q+K+ujEXsUaAdb5nwmlOJqpoJeCh5Fmq5A1NdF3BwkI8+GwTkH757NBZAS\n"
"SdEuN0pLZmA6LopOiMIy0LoIWknM5eWMa3e41CxCEFoMv48gFIVxDNJ/KAQAX7+K\n"
"ysYzIdlA3W3fBXXyGQIDAQAB"
);
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwRiedByAoS2"
"DUJAkm6qqfhlhNnpNbONf8W4giGERMBAvRA7mRGKa7+vtgJiepvQ/CX0np5MBAMXcL9t9YFZ30lmp4COBdr5nilTyUdLWns"
"cnhYIxneJIG3rzkmnhXaDsiemOlrLC2PEJu6jcek8qurJmQ7gpP0va45MwiTHHto1lSjjvF8xYAZSrTlbIqLo1f98lxg9xs"
"zHI6sSXwDqDpJfS0JORtw3Rcc731QFR1rR2EOAEZo6Zdo0cD1uOQJgLkv8drU9BDMsR9ErBuGSbZQzn2FAc4Bkmq/gNGYd1"
"HmdFkofwVkqu/dTYWXOumKDIVqRsLQ213vuvC0lzcLaJxQIDAQAB"
);
BIAP_AppStore* app_store = BIAP_CreateAppStore(BIAP_STORE_DEFAULT, native_platform_context, MyProductCallback, MyTransactionCallback, my_user_data);

◆ BIAP_RequestProducts()

void BIAP_RequestProducts ( struct BIAP_AppStore app_store,
const char *  nonconsumable_product_identifier_list[],
size_t  num_nonconsumables,
const char *  consumable_product_identifier_list[],
size_t  num_consumables,
const char *  subscription_product_identifier_list[],
size_t  num_subscriptions 
)

Requests product information from your connected app store.

Requests product information for the identifiers you supply from your connected app store. This information includes things like description and price. Information will be returned in your BIAP_ProductResponse callback.

Parameters
app_storeThe app store connection you want to request from.
nonconsumable_product_identifier_listAn array of strings containing the product identifiers of the non-consumable products you want information for.
num_nonconsumablesThe number of product identifiers in your nonconsumable_product_identifier_list.
consumable_product_identifier_listAn array of strings containing the product identifiers of the consumable products you want information for.
num_consumablesThe number of product identifiers in your consumable_product_identifier_list.
subscription_product_identifier_listAn array of strings containing the product identifiers of the subscription products you want information for.
num_subscriptionsThe number of product identifiers in your subscription_product_identifier_list.
Note
The InAppPurchase workflow is to always RequestProducts first. Then you use the object(s) returned from the callback(s) to pass as the parameter to BIAP_PurchaseProduct.

◆ BIAP_RequestReceiptRefresh()

void BIAP_RequestReceiptRefresh ( struct BIAP_AppStore app_store)

(Apple-only) Refreshes the user's purchases receipt on the file system.

Refreshes the user's purchases receipt on the file system. It is possible the receipt doesn't exist because it is a new device, or the receipt is out of date because the user has multiple devices, so this API will make a server request to update the receipt. This will trigger a BIAP_EVENT_TRANSACTION_RECEIPT_REQUEST_FINISHED or BIAP_EVENT_TRANSACTION_RECEIPT_REQUEST_FAILED callback in your BIAP_TransactionResponse callback.

Note
This is only useful for Apple platforms. You will get a BIAP_EVENT_TRANSACTION_RECEIPT_REQUEST_FAILED when calling on other platforms.
Parameters
app_storeThe app store handle you want to request from.
See also
BIAP_GetReceiptPath BIAP_GetTransactionOriginalJson

◆ BIAP_RestorePurchases()

void BIAP_RestorePurchases ( struct BIAP_AppStore app_store)

Requests all purchases a user has bought from the app store.

Requests all purchases a user has bought from the app store. Each product will trigger a BIAP_EVENT_TRANSACTION_RESTORED event in your BIAP_TransactionResponse callback. For Apple platforms, you are required to have a button that allows the user to restore all their purchases. The intent is to allow users to receover their purchases to a new device. For Android platforms, this has an additional use of retrieving the consumable purchase object you need to pass BIAP_ConsumePurchase in order to consume it.

Parameters
app_storeThe app store handle you want to request from.
See also
BIAP_ConsumePurchase

◆ BIAP_SetDebugLogging()

void BIAP_SetDebugLogging ( bool  should_enable)

Enables extra debug log messages in the library.

Enables extra debug log messages in the library. The default is false. You should generally keep this disabled for release builds.

Parameters
should_enableTrue will enable more debugging messages. False will disable.
See also
BIAP_IsDebugLogging

◆ BIAP_StartAppStore()

void BIAP_StartAppStore ( struct BIAP_AppStore app_store)

Starts the app store.

Starts the app store. This will trigger a transaction response callback with event type BIAP_EVENT_INIT_FINISHED or BIAP_EVENT_INIT_FAILED to let you know if the creation succeeded or failed. After BIAP_EVENT_INIT_FINISHED, you may call BIAP_GetAppStoreName to find out which store you connected with.

Parameters
app_storeThe app store instance to start.