# Localytics Destination

## Destination Info

* Accepts [Page](/docs/segment/connections/spec/page), [Identify](/docs/segment/connections/spec/identify), [Track](/docs/segment/connections/spec/track) calls.
* Refer to it as **Localytics** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object)

### Components

* [Browser](https://github.com/segment-integrations/analytics.js-integration-localytics)
* [iOS](https://github.com/segment-integrations/analytics-ios-integration-localytics)
* [Android](https://github.com/segment-integrations/analytics-android-integration-localytics)

## Connection Modes

[Learn more about connection modes.](/docs/segment/connections/destinations/#connection-modes)

### Device-Mode

* web: yes
* mobile: yes
* server: no

### Cloud-Mode

* web: no
* mobile: no
* server: no

Our Localytics mobile destination code is open sourced on GitHub. Feel free to
check it out:
[iOS](https://github.com/segment-integrations/analytics-ios-integration-localytics),
[Android](https://github.com/segment-integrations/analytics-android-integration-localytics).

## Getting Started

Once the Segment library is integrated with your site or app, toggle Localytics
on in your Segment destinations, and add your application's **App Key** which
you can find in your Localytics app settings. These new settings will take up to
an hour to propogate to all of your existing users. For new users it'll be
instanteneous!

If you are using version 1.3.0 or higher of the Segment-Localytics Android SDK,
you can include a `localytics.xml` file in your Android project's `res/values`
folder to define your settings. Note that any settings entered in the Segment UI
will override the equivalent values defined in your `localytics.xml` file. You
can read more about the `localytics.xml` file in [Localytics's documentation
here](https://docs.localytics.com/dev/android.html#include-localytics-xml-file).

Including a settings xml file in conjunction with a Segment-Localytics iOS SDK
is not yet supported.

**Note:** Localytics does not accept cloud-mode data, so you must use a device-mode library ( such as [Analytics.js](/docs/segment/connections/sources/catalog/libraries/website/javascript/),
[iOS](/docs/segment/connections/sources/catalog/libraries/mobile/ios/)/[Android](/docs/segment/connections/sources/catalog/libraries/mobile/android/) or [React Native](/docs/segment/connections/sources/catalog/libraries/mobile/react-native/)), with the Localytics SDKs [bundled](/docs/segment/connections/spec/mobile-packaging-sdks/) in order to send data to Localytics.

You must also add the Maven Localytics repo (since Localytics doesn't publish it on Maven Central). You can see an example of how to add that
in the [@segment-integrations/analytics-android-integration-localytics](https://github.com/segment-integrations/analytics-android-integration-localytics/blob/master/build.gradle#L44) repository.

## Identify

When you call [`identify`](/docs/segment/connections/spec/identify/), we'll set the Localytics
customer Id, and set any special Localytics traits you provide, such as `name`,
or `email`, and any custom traits as well.

## Track

Whenever you call [`track`](/docs/segment/connections/spec/track/), we'll log an event with
Localytics. [`track`](/docs/segment/connections/spec/track/) takes the name of the event and any
optional properties you want to associate with the event.

## Push Notifications

Push notifications on Android require a bit of extra work to setup.

* First, you need to make sure Localytics is being bundled. You can find out
  more information about bundled integrations in our [Android documentation](/docs/segment/connections/sources/catalog/libraries/mobile/android/#about-mobile-connection-modes).
* Follow Localytics' documentation to [set up the permission in your
  AndroidManifest.xml](http://docs.localytics.com/dev/android.html#modify-androidmanifest-push-android).
  Specifically, the **AndroidManifest** changes regarding the `GcmReceiver`,
  `GcmListenerService`, `InstanceIDListenerServer`, and `PushTrackingActivity`
  classes.
* In lieu of step four, you will register the Push receiver in your Activity or
  Application class within a Segment `onIntegrationReady` method:

```java
@Override protected void onResume() {
    super.onResume();

     Analytics.with(this).onIntegrationReady(BundledIntegration.LOCALYTICS, new Callback() {
      @Override public void onIntegrationReady(Object integration) {
        Localytics.registerPush("YOUR-SENDER-ID");
      }
    });
}
```

## Settings

Segment lets you change these destination settings from the Segment app without having to touch any code.

| Field                                 | Description                                                                                                                                                                                                                                                                                                                                                                                             | Required | Type    |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
| App Key                               | You can find your App Key in your Localytics \[Settings page]\(http://www.localytics.com/).                                                                                                                                                                                                                                                                                                             | Yes      | string  |
| Custom Dimensions                     | Localytics only accepts custom dimensions that have been pre-set in your app. Make sure to set these up in Localytics first, under Settings > Apps and then editing your app settings. You should then map the \`trait\` in an identify call or the \`property\` in a track call to the corresponding custom dimension you want to send. For e.g. you might map \`gender\` with custom dimension \`0\`. | No       | map     |
| Session Timeout Interval              | If an App stays in the background for more than this many seconds, start a new session when it returns to foreground.                                                                                                                                                                                                                                                                                   | No       | number  |
| Use Organization Scope for Attributes | This allows a user to set the \`profileScope\` of attributes within Localytics to Organization. If this is enabled, the attributes that you set for a user will be available across all of your apps in Localytics. If it's unchecked, we'll use the default SDK behavior of Application scoping.                                                                                                       | No       | boolean |