> For the complete documentation index, see [llms.txt](https://movile.gitbook.io/kiwi-manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://movile.gitbook.io/kiwi-manual/using-plugins-to-trigger-custom-actions.md).

# Using Plugins to trigger custom actions

The plugins feature is useful to trigger custom actions based on the occurrence of our Events. For example, everytime an OPEN event is sent by your app, Kiwi can perform some action.

The actions available are:

* Invoke an AWS's Lambda function (EVENT\_TO\_LAMBDA)
* Send the event to an AWS's SQS queue (EVENT\_TO\_SQS)
* Send the event to an AWS's SNS topic (EVENT\_TO\_SNS)
* Send the event to an AWS's Kinesis stream (EVENT\_TO\_KINESIS)
* Snapshot the state of some Kiwi's entity i.e. AppInstall (SNAPSHOT)
* Perform a HTTP request using any Kiwi's information (EVENT\_TO\_URL)

To configure a new plugin:

* Go to your app's page, click on `Settings` > `Plugins`. You'll see all the plugins configured for your app.
* Press the `+New` button.
* Fill the `Description` field with the meaning of your plugin.
* Choose the value `EVENT` in the `Plugin Type` field.
* Choose one of the plugins listed above and select it into the `Plugin Handler Type`field.
* Include all the event types you desire in the `Supported Events` field, or, alternatively, mark the `Support All Events` button. Putting an event type in this list means that every time an event of this type is sent to Kiwi, the plugin will be triggered.
* In case you add `CUSTOM` events to the `Supported Events` field, the `App Type Pattern` field will show up. This field accepts Java regular expressions and it defines which `CUSTOM` events are supported by matching its app type against the expression.
* The next configurations depends on the `Plugin Handler Type` you choosed. Follow the instructions above.
* Press the `Save` button.
* You are done! :)

## EVENT\_TO\_URL Plugin

This plugin can perform a HTTP request to any endpoint, based on Kiwi's data.

Continuing the configuration process described above:

* In the field `URL`, insert the URL that will be called by the plugin (See: the **Wildcards** below).
* In the field `HTTP Method`, choose between `GET` and `POST`.
* If the http method is `POST`, fill the field `Body` with the content you are about to post (See: the **Wildcards** below).
* Again, if the http method is `POST`, fill the field `Content Type` if you desire.
* If your request fails, Kiwi will retry it. In the field `Retry Interval in Seconds`, put the interval to wait between retries. Kiwi will try to complete your request at most in three attempts.

### Wildcards

When configuring an URL or a request body, you can use placeholders that will be replaced with real Kiwi values. We call it **Wildcards**.

For example, lets say will want to request the URL `http://myservice.com/${event.appInstallId}/${event.userId}`. `${event.appInstallId}` and `${event.userId}` will both be replaced with the real values of the appInstallId and userId, both part of the Event domain.

#### Wildcard composition

Take the wildcard ${event.appInstallId} as an example, it is a string composed of three parts:

* **Wildcard Mode:** The first character of the wildcard, it must be present in one of the two options:
  * **$**: Mandatory. If the value represented by the given wildcard is not present (i.e. `null`), the request will fail.
  * **#**: Optional. If the value represented by the given wildcard is not present (i.e. `null`), the wildcard will be removed from the URL/Body.
* **Wildcard Domain:** The Kiwi's entity that holds the value you want. In our example, the domain is `event`.
* **Wildcard Field:** The value after the `.` character, it represents the property of the Wildcard's entity. In our example, the field is `appInstallid`.

#### Supported Wildcards:

* `event` domain:
  * `event.applicationId`
  * `event.productId`
  * `event.applicationKey`
  * `event.userId`
  * `event.appInstallId`
  * `event.serverEventTime`
  * `event.requesterLocalTime`
  * `event.requesterEventTime`
  * `event.deviceLanguage`
  * `event.deviceTimezone`
  * `event.deviceSystemName`
  * `event.deviceSystemVersion`
  * `event.deviceManufacturer`
  * `event.deviceModel`
  * `event.installedAt`
  * `event.appSdkVersion`
  * `event.countryByIp`
  * `event.deviceCountry`
  * `event.appVersion`
  * `event.androidId`
  * `event.openUdid`
  * `event.ifa`
  * `event.imei`
  * `event.odin1`
  * `event.ifv`
  * `event.advertisingId`
  * `event.scenarioId`
  * `event.eventTypeName`
  * `event.eventTypeId`
  * `event.appEventType`
  * `event.payload` (this wildcard can also be in the form `event.payload.key1`, where `key1` is a key of the `payload` map)
  * `event.currency`
  * `event.price`
* `appInstall` domain:
  * `appInstall.platformName`
  * `appInstall.platformId`
  * `appInstall.initialAppVersion`
  * `appInstall.initialSdkVersion`
  * `appInstall.lastAppUpdatedAt`
  * `appInstall.isAppInstallInvalidated`
  * `appInstall.pushToken`
  * `appInstall.pushEnvironmentName`
  * `appInstall.pushEnvironmentId`
  * `appInstall.pushTokenInvalidated`
  * `appInstall.pushTokenInvalidatedAt`
  * `appInstall.pushTokenRefreshedAt`
  * `appInstall.lastOpenAt`
  * `appInstall.carrier`
  * `appInstall.carrierId`
  * `appInstall.msisdn`
  * `appInstall.newsletterEmail`
  * `appInstall.platformAccountEmail`
  * `appInstall.subscribedToNewsletter`
  * `appInstall.scenarioCountry`
  * `appInstall.activeSubscriptions`
  * `appInstall.campaign`
  * `appInstall.campaignAsDefault`
  * `appInstall.externalMediaCampaignId`
  * `appInstall.externalMediaCampaignName`
  * `appInstall.externalMediaNetwork`
  * `appInstall.externalMediaUserId`
  * `appInstall.externalMediaSite`
  * `appInstall.externalMediaAd`
  * `appInstall.externalMediaGroup`
  * `appInstall.externalMediaClickId`
  * `appInstall.accountUUID`
  * `appInstall.tags`
* `user` domain: 

  the `.<namespace>` and `.<key>` are optional, if present will return only the value of the key, otherwise return a json representation of all data.

  * `user.privateSettings.<namespace>.<key>`
  * `user.sharedSettings.<namespace>.<key>`
* `subscription` domain:
  * `subscription.id`
  * `subscription.monetizationPlatformId`
  * `subscription.monetizationPlatformName`
  * `subscription.subscriptionTypeId`
  * `subscription.subscriptionTypeName`
  * `subscription.subscriptionStatusId`
  * `subscription.subscriptionStatusName`
  * `subscription.sku`
  * `subscription.currencyCode`
  * `subscription.price`
  * `subscription.priceInUSDollars`
  * `subscription.priceConvertedAt`
  * `subscription.receiptData`
  * `subscription.externalTransactionId`
  * `subscription.createdAsTrial`
  * `subscription.trialDurationInDays`
  * `subscription.activatedAt`
  * `subscription.expiresAt`
  * `subscription.lastRenewAt`
  * `subscription.lastSyncAt`
  * `subscription.renewCount`
  * `subscription.extraData`
  * `subscription.lastRenewSyncAt`
  * `subscription.converted`
  * `subscription.convertedAt`
  * `subscription.expiredAt`
  * `subscription.activationsCount`
  * `subscription.originalReceipt`
  * `subscription.cancelReasonId`
  * `subscription.cancelReasonName`
  * `subscription.renewPeriodId`
  * `subscription.renewPeriodName`
  * `subscription.accounts`
  * `subscription.environmentId`
  * `subscription.environmentName`
  * `subscription.mediaInformation.campaignId`
  * `subscription.mediaInformation.campaignNetwork`
  * `subscription.mediaInformation.raw`
* `account` domain:
  * `account.accountUUID`
  * `account.identityPool`
  * `account.email`
  * `account.msisdn`
  * `account.facebookId`
* `custom` domain (This domain contains useful functions, it isn't related to any Kiwi's entity):
  * `custom.now`: the current time in milliseconds.

### Examples

* URL:&#x20;
  * `https://service.io/monitoring?teste=${event.appInstallId}&teste2=${appInstall.platformName}&teste3=${appInstall.platformId}#teste4=${custom.now}`
  * `https://service.io/${event.appInstallId}/#{appInstall.platformName}`
* Body:

  ```
  {
    "key1": "${event.appInstallId}",
    "key2": "${appInstall.platformName}",
    "key3": "#{appInstall.platformId}",
    "key4": "value4"
  }
  ```

## EVENT\_TO\_LAMBDA Plugin

This plugin invokes an AWS's Lambda function.

## EVENT\_TO\_SQS Plugin

This plugin sends the event to an AWS's SQS queue.

## EVENT\_TO\_SNS Plugin

This plugin sends the event to an AWS's SNS topic.

## EVENT\_TO\_KINESIS Plugin

This plugin sends the event to an AWS's Kinesis stream.

## SNAPSHOT Plugin

This plugin snapshots the state of some Kiwi's entity i.e. AppInstall.