# Custom actions

Batch Actions is a module allowing you to register remotely-configurable runnable code to the SDK, when simple deeplinks wouldn't be enough. They can be triggered at any time by the SDK, allowing you to focus on the action code rather than when to trigger it.

Batch comes with builtin actions (deeplinking, user data edition, etc...)

{% hint style="info" %}
Note: On iOS, actions are mainly used for mobile landings, but their usage will be extended in future Batch versions.
{% endhint %}

## Registering an action

An action has two components:

* An identifier (case-unsensitive string), which will allow you to reference this action
  * While the identifier string is up to you, it cannot start with "batch.": these identifiers are reserved for built-in actions.
* An implementation block

Registering them is easy, and should be done every time your app starts, right before starting Batch:

{% tabs %}
{% tab title="Swift" %}

```swift
BatchActions.register(BatchUserAction(identifier: "<YOUR_ACTION_NAME>",
                                      actionBlock: { (identifier: String, arguments: [String : Any], source: BatchUserActionSource?) in
    // Your action code here
}))
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
BatchUserActionBlock alertActionBlock = ^(NSString * _Nonnull identifier, NSDictionary<NSString *,NSObject *> * _Nonnull arguments, id<BatchUserActionSource>  _Nullable source) {
    // Your action code here
};
[BatchActions registerAction:[BatchUserAction userActionWithIdentifier:@"<YOUR_ACTION_NAME>"
                                                           actionBlock:alertActionBlock]];
```

{% endtab %}
{% endtabs %}

The source argument represents what caused the action to be triggered. You can use `isKindOfClass` (or a swift cast using `as?`) to check what source it comes from, and read what you need.\
Two sources classes are currently used: `BatchPushMessage` and `BatchManualUserActionSource`. More will be added in the future.

## Unregistering an action

Simply call the unregister method with the previously set identifier:

{% tabs %}
{% tab title="Swift" %}

```swift
BatchActions.unregister(actionIdentifier: "<YOUR_ACTION_NAME>")
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
[BatchActions unregisterActionIdentifier:@"<YOUR_ACTION_NAME>"];
```

{% endtab %}
{% endtabs %}

## Triggering an action

You might want to re-use the code you've already registered to Batch from your own code by triggering an action.

Simply give Batch the action identifier and arguments, and it will call your action:

{% tabs %}
{% tab title="Swift" %}

```swift
BatchActions.perform(actionIdentifier: "alert", arguments: ["title": "Hello", "body": "How are you doing?"])
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
[BatchActions performActionIdentifiedBy:@"alert" withArguments:@{@"title":@"Hello", @"body":@"How are you doing?"}];
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Note: Built-in Batch actions are reserved to the SDK and not triggerable that way
{% endhint %}

## Built-in actions

Batch provide a set of pre-defined actions, allowing you to easily trigger a specific behavior without implementing them yourself.

### `batch.dismiss`

Simply dismiss the notification and exit

**Arguments**

`N/A`

***

### `batch.deeplink`

Open the provided deeplink (will call the Deeplink Interceptor if one is set).

**Arguments** *(required)*

<table><thead><tr><th width="137.6171875">Name</th><th>Value</th></tr></thead><tbody><tr><td><code>l</code></td><td><strong>String</strong> - <em>Required</em><br>The deeplink to open<br><em>E.g.</em><code>{"l":"https://google.com"}</code></td></tr><tr><td><code>li</code></td><td><strong>Boolean</strong> - <em>Optional - Default false</em><br>If true the Batch SDK will try to open your deeplink inside the app<br><em>E.g.</em><code>{"li":false}</code></td></tr></tbody></table>

***

### `batch.ios_request_notifications`

Show the notification permissions pop-up.

**Arguments**

`N/A`

***

### `batch.ios_redirect_settings`

Open the notifications settings of the current application.

**Arguments**

`N/A`

***

### `batch.ios_smart_reoptin`

Checks if the user has already been asked for notifications, if not it shows the notification permissions pop-up, otherwise it opens the notifications settings of the current application.

**Arguments**

`N/A`

***

### `batch.user.tag`

Add or remove a tag associated with the current user.

**Arguments** *(required)*

<table><thead><tr><th width="146.40625">Name</th><th>Value</th></tr></thead><tbody><tr><td><code>a</code></td><td><strong>String</strong> - <em>Required</em><br>The action to perform.<br>Acceptable values are add and remove<br><em>E.g.</em><code>{"a":"remove"}</code></td></tr><tr><td><code>c</code></td><td><strong>String</strong> - <em>Required</em><br>The collection to use when updating the tag<br><em>E.g.</em><code>{"c":"actions"}</code></td></tr><tr><td><code>t</code></td><td><strong>String</strong> - <em>Required</em><br>The tag to update<br><em>E.g.</em><code>{"t":"has_bought"}</code></td></tr></tbody></table>

***

### `batch.user.event`

Send an event with associated tags and data.

**Arguments** *(required)*

<table><thead><tr><th width="145.296875">Name</th><th>Value</th></tr></thead><tbody><tr><td><code>e</code></td><td><strong>String</strong> - <em>Required</em><br>The name of the event to send<br><em>E.g.</em><code>{"e":"my_awesome_event"}</code></td></tr><tr><td><code>l</code></td><td><strong>String</strong> - <em>Optional - default null</em><br>The label associated with the event<br><em>E.g.</em><code>{"l":"label1"}</code></td></tr><tr><td><code>t</code></td><td><strong>Array</strong> - <em>Optional - default empty list</em><br>A list of tags to be send with the event<br><em>E.g.</em><code>{"t":["tag1","tag2","tag3"]}</code></td></tr><tr><td><code>a</code></td><td><strong>Object</strong> - <em>Optional - default empty object</em><br>The data to send with the event<br><em>E.g.</em><code>{"a":{"key":"value","key2":12,"key3":true}}</code></td></tr></tbody></table>

***

### `batch.group`

Execute a list of up to 10 nested actions successively.

**Arguments** *(required)*

<table><thead><tr><th width="137.6171875">Name</th><th>Value</th></tr></thead><tbody><tr><td><code>actions</code></td><td><strong>Array</strong> - <em>Required</em><br>A list of actions to perform. This list must not be longer than 10 elements and can't contains batch.group actions<br><em>E.g.</em><code>{"actions":[["batch.deeplink",{"l":"https://google.com"}],["batch.user.tag",{"add":"..."}]]}</code></td></tr></tbody></table>

***

### `batch.ios_tracking_consent`

On iOS 14, asks for Tracking consent using the AppTrackingTransparency framework. If the user has already been asked and refused to consent, opens the app's settings where tracking can be enabled. Does nothing on iOS 13 and earlier, or if tracking has been restricted by the device's manager. Your application needs to have a 'NSUserTrackingUsageDescription' key in its Info.plist or else iOS will crash it. Available since Batch 1.16.

**Arguments**

`N/A`

***

### `batch.clipboard`

Copy a text to the device's clipboard.

**Arguments** *(required)*

<table><thead><tr><th width="137.6171875">Name</th><th>Value</th></tr></thead><tbody><tr><td><code>t</code></td><td><strong>String</strong> - <em>Required</em><br>The text to copy<br><em>E.g.</em><code>{"t":"My awesome text !"}</code></td></tr></tbody></table>

***

### `batch.rating`

On iOS 10.3+, asks for the user to rate the app using SKStoreReviewController (this API's restrictions apply). Available since Batch 1.17.

**Arguments**

`N/A`

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.batch.com/developer/sdk/ios/advanced/custom-actions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.