# Freshpaint iOS SDK Reference

## Initialization and Configuration

### Importing the SDK

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

```swift
import FreshpaintSDK
```

{% endtab %}

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

```objectivec
#import <FreshpaintSDK/FPAnalytics.h>
```

{% endtab %}
{% endtabs %}

### Initializing the SDK

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

```swift
let configuration = FreshpaintConfiguration("<your environment id>")
configuration.trackApplicationLifecycleEvents = true;
configuration.recordScreenViews = true;
Freshpaint.setup(with: configuration)
```

{% endtab %}

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

```objectivec
    FPAnalyticsConfiguration *configuration = [FPAnalyticsConfiguration configurationWithWriteKey:@"<your environment id>"];
    configuration.trackApplicationLifecycleEvents = YES;
    configuration.recordScreenViews = YES;
    [FPAnalytics setupWithConfiguration:configuration];
```

{% endtab %}
{% endtabs %}

You can get your environment id from the [Freshpaint sources page](https://app.freshpaint.io/sources).

The `FPAnalyticsConfiguration` class provides the following configuration options:

| Name                            | Swift/Objective-C Type          | Description                                                                                                                        | Default      |
| ------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| flushAt                         | `UInt` /`NSUInteger`            | How many events to queue before flushing the queue.                                                                                | `20`         |
| flushInterval                   | `TimeInterval`/`NSTimeInterval` | The maximum amount of time to wait before flushing queued events.                                                                  | `10 seconds` |
| maxQueueSize                    | `UInt`/`NSUInteger`             | The maximum number of events to queue before starting to drop the oldest ones.                                                     | `1000`       |
| recordScreenViews               | `Bool`/`BOOL`                   | Whether or not screen view changes will automatically be recorded.                                                                 | `NO`         |
| trackApplicationLifecycleEvents | `Bool`/`BOOL`                   | Whether or not the `Application Installed`, `Application Updated`, and `Application Opened` events should be automtically tracked. | `NO`         |

## iOS SDK API

### track

The `track` call can be used to manually send data to your destinations.

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

```swift
Freshpaint.shared().track(
    "Purchase", 
    properties: ["price": 500]
)
```

{% endtab %}

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

```objectivec
[[FPAnalytics sharedAnalytics]
              track:@"Purchase" 
              properties:@{ @"price": @500 }];
```

{% endtab %}
{% endtabs %}

| Argument   | Swift/Objective-C Type            | Required | Description                                   |
| ---------- | --------------------------------- | -------- | --------------------------------------------- |
| event      | `String`/`NSString *`             | Yes      | The name of the event to send.                |
| properties | `[String : Any]`/`NSDictionary *` | No       | Additional properties to attach to the event. |

### identify

The `identify` call attaches an identity or user properties to the user.

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

```swift
Freshpaint.shared().identify(
    "ada.lovelace@example.com", 
    traits: [
      "email": "ada.lovelace@example.com", 
      "name": "Ada Lovelace"
    ]
);
```

{% endtab %}

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

```objectivec
[[FPAnalytics sharedAnalytics] 
              identify:@"ada.lovelace@example.com"
              traits:@{ @"email": @"ada.lovelace@example.com",
                        @"name": @"Ada Lovelace" }]
```

{% endtab %}
{% endtabs %}

| Argument | Swift/Objective-C Type            | Required | Description                                       |
| -------- | --------------------------------- | -------- | ------------------------------------------------- |
| userId   | `String`/`NSString *`             | No       | The id to attach to the user.                     |
| traits   | `[String : Any]`/`NSDictionary *` | No       | Additional user properties to attach to the user. |

### screen

The `screen` call triggers a screen event. This is the mobile equivalent of a pageview event. Some destinations will treat this event specially.

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

```swift
Freshpaint.shared().screen(
    "Home Screen", 
    properties: ["A/B Test Variant": "A"]
);
```

{% endtab %}

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

```objectivec
[[FPAnalytics sharedAnalytics] 
              screen:@"Home Screen"
              properties:@{ @"A/B Test Variant": @"A" }]
```

{% endtab %}
{% endtabs %}

| Argument   | Swift/Objective-C Type            | Required | Description                                   |
| ---------- | --------------------------------- | -------- | --------------------------------------------- |
| name       | `String`/`NSString*`              | Yes      | The name of the screen.                       |
| properties | `[String : Any]`/`NSDictionary *` | No       | Additional properties to attach to the event. |

### group

The group call associates the user with a user group. Some destinations let you work with groups of users. For example, [Amplitude lets you group users together](https://developers.amplitude.com/docs/group-identify-api) and then perform analytics on the individual groups. Most often, a group of users is all users that work for a single organization.

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

```swift
Freshpaint.shared().group(
    "Google", 
    traits: [
      "plan": "enterprise", 
      "sign-up-date": "04/04/2019"
    ]
);
```

{% endtab %}

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

```objectivec
[[FPAnalytics sharedAnalytics]
              group:@"Google"
              traits:@{ @"plan": @"enterprise",
                        @"sign-up-date": "04/04/2019" }]
```

{% endtab %}
{% endtabs %}

| Argument | Swift/Objective-C Type            | Required | Description                                   |
| -------- | --------------------------------- | -------- | --------------------------------------------- |
| groupId  | `String`/`NSString *`             | Yes      | The id of the group to add the user to.       |
| traits   | `[String : Any]`/`NSDictinoary *` | No       | Additional properties to attach to the group. |

### alias

The `alias` call can be used to specify one user id as an alias for another user id. Calling this will alias the current user's identity to the new provided identity. This is needed to implement identify for some destinations, specifically Mixpanel and Kissmetrics.

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

```swift
Freshpaint.shared().alias("ada.lovelace@example.com")
```

{% endtab %}

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

```objectivec
[[FPAnalytics sharedAnalytics] alias:@"ada.lovelace@example.com"];
```

{% endtab %}
{% endtabs %}

| Argument | Swift/Objective-C Type | Required | Description                                              |
| -------- | ---------------------- | -------- | -------------------------------------------------------- |
| newId    | `String`/`NSString *`  | Yes      | The id you want to alias the current user's identity to. |

### reset

The `reset` call clears any local Freshpaint data attached to this user. This does not clear any local data for any of your destinations. For example this may be useful if a user logs out and logs in to a different account.

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

```swift
Freshpaint.shared().reset()
```

{% endtab %}

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

```objectivec
[[FPAnalytics sharedAnalytics] reset]
```

{% endtab %}
{% endtabs %}


---

# 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://documentation.freshpaint.io/reference/developer/freshpaint-ios-sdk-reference.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.