The Swrve in-app messaging system may be used to promote aspects of your game or even cross-promote a player to another game Kongregate publishes. To support this, your game must handle a special PROMO_AWARD event the Kongregate SDK may fire. The Kongregate SDK fires this even in response to a Swrve in-app message deep link that conforms to a specific format. The Kongregate PROMO_AWARD event may contain a set of parameter which define what your game should award to the user. Acceptable values for Promo Awards should be worked out with your Kongregate Producer.
You must use the newer KongregateAPI.SetEventBundleListener() method to register an event listener that will receive optional JSON payloads with the event. This listener can replace the older KongregateAPI.SetEventListener(), which only included a single event name parameter.
The format of the JSON payload for the PROMO_AWARD event will be as follows:
{ "promoId" : "ebf_promo",
"item": "some_item",
"currency": "gold",
"amount": 100 ,
"installUrl" : "https://play.google.com/store/apps/details?id=com.kongregate.mobile.endlessbossfight.google&hl=en" }
This will be a unique ID for the promotion. You may use this ID to verify the same award is not given to the same user twice. Once your game processes the award, you should pass it to KongregateAPI.Analytics.FinishPromoAward(promoId). When invoked the Kongregate SDK will update Swrve User Properties that should prevent Swrve from scheduling the in-app message again.
Your game should handle the case of the same promo award event occuring again. There are edge cases where a user may retrieve the same message twice. These edge cases include:
This identifies an item to award with this promo. Valid values for item awards should be worked out with your Kongregate Producer.
This identifies a type of currency to award in your game (e.g. gold or gems). Valid values for currency awards should be worked out with your Kongregate Producer
The amount of currency to award. Valid amounts should be worked out with your Kongregate Producer.
This will be an URL your game should open after awarding the item and invoking KongregateAPI.Analytics.FinishPromoAward(promoId).
The Swrve in-app messaging system used for Promo Awards supports arbitrary additional JSON parameters to be included with this event. If desired, you may work out additional parameters and values that your game will handle. For example, a message to display or screen in the game to show after finishing the Award.
The KongregateAPI.Analytics.FinishPromoAward(promoId) API call will update Swrve User Properties that are used to filter Swrve in-app messages. Invoke this method once you finish processing the PROMO_AWARD event. The method should be invoked whether the award was given or determined that award should not be given for whatever reason.
The PROMO_AWARD event will always include the promoId parameter, which you should include when you invoke KongregateAPI.Analytics.FinishPromoAward(promoId). The remaining parameters are all optional and define what your game should give as an award, and possibly an URL to follow after the award event is handled. Since these events are coming from the client it is inherently insecure. Depending on the game and value of the awards, you probably want to implement some sanity checks and limits on what may be awarded through this mechanism. Whether your game honors the award or determines it’s a duplicate or falls beyond some threshold for promo awards, still invoke KongregateAPI.Analytics.FinishPromoAward(promoId) to prevent the award message from legitimately being shown again.
If you are adding a promotion to a game that is already released, it’s a good idea to add a supported_awards parameter. This will enable us to target the promotion only to clients that support the award. This is much easier and less error prone than specifying individual app versions in the in-app message target. It’d be easy to forget to update the in-app message promo when a new version is released. This will help protect against that and should make the in-app message configurations more readable.
To update the user property, invoke the following code after you receive the KONGREGATE_READY_EVENT.
// this will update the Swrve supported_awards user property to say this client can
// award coins and gems
KongregateAPI.GetAPI().Analytics.GameUserUpdate(new Dictionary<string,object>() {
{ "supported_awards", "coins gems" }
});
The GameUserUpdate(...) method exists in the native iOS and Android APIs as well.
The in-app messages will occur in response to Swrve event triggers. There are many events automatically fired by the Swrve and Kongregate SDKs, which may be used as triggers. You may want to add additional triggers at points when it makes sense for an in-app message to occur. At the moment your game does not get notified when a message is displayed and there’s no way to pause your game until it’s dismissed. We do hope to add callbacks when messages appear and are dismissed in a future SDK release, which could be used to pause the game while a message is shown. Until then you probably only want in-app messages to appear at times when the game is already paused and waiting for some user interaction. For example, if your game has main menu or game over screen.
// The Swrve prefix has the effect of sending the event only to Swrve. It will not be exctracted through ETL. The payload may
// be used to add further details, or null.
KongregateAPI.GetAPI().Analytics.AddEvent("swrve.main_menu", payload);
You may setup test in-app message promotions in Sandbox mode for your app. You can also setup a device as a QA device and targert the messages to just that device. To trigger the PROMO_AWARD event, set the deep link action for one of the buttons as the following.
kong_promo_award { "promoId": "ebf_promo1", "item": "some_item", "currency": "gold", "amount": 100, "installUrl": "http://google.com" }