Idea

Dear PlayFab Community,

I would like to propose an enhancement to the Server API's GrantItemsToUserResult object (the return value from GrantItemsToUser()). The function is very rich in its capabilities to recursively evaluate Bundles/Containers and ResultTables. However, that "hierarchical" information is not propagated back to the caller. All we get are the final ItemResults.

Here is the documentation.

Here is the definition (TypeScript) for the result object:

    /** https://api.playfab.com/Documentation/Server/datatype/PlayFab.Server.Models/PlayFab.Server.Models.GrantItemsToUserResult */
    interface GrantItemsToUserResult {
        /** Array of items granted to users. */
        ItemGrantResults?: GrantedItemInstance[],
    }

And the GrantedItemInstance:

    /** 
     * Result of granting an item to a user
     * https://api.playfab.com/Documentation/Server/datatype/PlayFab.Server.Models/PlayFab.Server.Models.GrantedItemInstance
     */
    interface GrantedItemInstance {
        /** Unique PlayFab assigned ID of the user on whom the operation will be performed. */
        PlayFabId?: string,
        /** Unique PlayFab assigned ID for a specific character owned by a user */
        CharacterId?: string,
        /** Result of this operation. */
        Result: boolean,
        /** Unique identifier for the inventory item, as defined in the catalog. */
        ItemId?: string,
        /** Unique item identifier for this specific instance of the item. */
        ItemInstanceId?: string,
        /** Class name for the inventory item, as defined in the catalog. */
        ItemClass?: string,
        /** Timestamp for when this instance was purchased. */
        PurchaseDate?: string,
        /** Timestamp for when this instance will expire. */
        Expiration?: string,
        /** Total number of remaining uses, if this is a consumable item. */
        RemainingUses?: number,
        /** The number of uses that were added or removed to this item in this call. */
        UsesIncrementedBy?: number,
        /** 
         * Game specific comment associated with this instance when it was added to the
         * user inventory.
         */
        Annotation?: string,
        /** Catalog version for the inventory item, when this instance was created. */
        CatalogVersion?: string,
        /** 
         * Unique identifier for the parent inventory item, as defined in the catalog, for
         * object which were added from a bundle or container.
         */
        BundleParent?: string,
        /** CatalogItem.DisplayName at the time this item was purchased. */
        DisplayName?: string,
        /** Currency type for the cost of the catalog item. */
        UnitCurrency?: string,
        /** Cost of the catalog item in the given currency. */
        UnitPrice: number,
        /** Array of unique items that were awarded when this catalog item was purchased. */
        BundleContents?: string[],
        /** A set of custom key-value pairs on the inventory item. */
        CustomData?: { [key: string]: string },
    }

Ideally, we would get some additional information in the GrantItemsToUserResult object: an array of intermediate objects (by ID) and their counts. Maybe something like:

interface IGrantedWorkingObjectType: "Bundle" | "Container" | "ResultTable";
interface IGrantedWorkingObject {
   Id: string,
   Type: IGrantedWorkingObjectType,
   Count: number
}

Then the GrantItemsToUserResult object could be extended:

    /** https://api.playfab.com/Documentation/Server/datatype/PlayFab.Server.Models/PlayFab.Server.Models.GrantItemsToUserResult */
    interface GrantItemsToUserResult {
        /** Array of items granted to users. */
        ItemGrantResults?: GrantedItemInstance[],
        WorkingObjects?: IGrantedWorkingObject[]
    }

You get the idea.

Having the GrantItemsToUser() provide this information would allow us access to some of the objects that were used to evaluate the resultant ItemInstances and perform any necessary operations that might have come from the working objects that were used in the evaluation.

Otherwise, the GrantItemsToUser() is incredibly opaque. Since we have limits on the number of APIs we can invoke in a single CloudScript call, access to this information is potentially very important.

Additionally, the GrantedItemInstance.BundleParent property appears to be an *internal* ID value, and not something that we can easily reference with the Server API. The documentation shows that it's a user-friendly value, but when I look at the value, it's more like "BundleParent":"C4544EEC77A6897E".

Thank you for your consideration!