npm package: @ringierag/ringier-pixel-react-native
Description: Ringier Pixel for React Native implementations
Author: Ringier AG
Latest version: 0.5.0

## DEPRECATED
This library has been deprecated and is no longer supported.

# Ringier Pixel for React Native implementations

**Current Version: **Current Version: 0.5.0****

In order to use this library you need a **Sherlock AppId**. If you do not have one please reach out to the Sherlock team who will guide you through onboarding the Pixel


## Install

```
npm install @ringierag/ringier-pixel-react-native --save
```

### Dependencies

This library needs the following packages to be available in your project:

* `react-native-device-info`

## Documentation

### Tracker initialization

For your **testing** environment do:
```js
import { RingierTracker } from '@ringierag/ringier-pixel-react-native';

let tracker = new RingierTracker(
  'unique-app-id',
  true, // send all events to our test environment
);
```

For **production** it's sufficient to do:
```js
let tracker = new RingierTracker('unique-app-id');
```

You can register an error handler in case something goes wrong:
```js
tracker.onError((err) => {
  console.log(err);
});
```

### Tracking API

#### Page View
```js
tracker.trackPageView(inAppUrl, title, referrer, contentId);

// example
tracker.trackPageView(
  '/news/politik/some-article-page-id8670212.html', // URI, or other in-app identifier of the "page"
  'The title of the article - and a subline', // Text of the headline and sub-headline
  '/news/politik/', // Referral URI or other in-app identifier
  '8670212' // Article identifier, often known as content identifier
);
```

#### Page Ping
The page ping API will send an event every 10th second as long as the following is true:
* Page ping is enabled with `enablePagePings()`
* `onMomentumScrollEnd` added around content (as seen below).
* App is in the foreground.
* User has interacted with the app within the last 10 seconds.

The ping is dependent on `trackPageView` as it's sending the data provided by last called `trackPageView`.

The `onMomentumScrollEnd` is needed to track what pixels the user has seen and to check if the user is active.

```js
<ScrollView onMomentumScrollEnd={(event) => tracker.handleScroll(event)}>
  // View content
</ScrollView>
```

Enabling page pings as below will send pings in the background.
```js
tracker.enablePagePings();
```

Then track page views as normal on each page.
```js
tracker.trackPageView(
  '/news/politik/some-article-page-id8670212.html',
  'The title of the article - and a subline',
  '/news/politik/',
  '8670212'
);
```

It is also possible to disable page pings with `tracker.disablePagePings()`, for example in a settings screen.
Important to note is that you need to enable page pings when you exit the settings screen.

```js
tracker.disablePagePings();
```

#### Set UserId

```js
tracker.setUserId(
  unhashedUserId, // Will be hashed by the function
  shouldHash = true // Can be set to false if you have already hashed the userId (bool) (default = true)
)
```

#### User Data

```js
tracker.trackUserData(
  gender, // m or f (string)
  ageGroup, // e.g. 25-30 (string)
  zipCode, // (string)
  city, // (string)
  country, // (string)
  education, // (string)
  income, // (string)
  extraData // (object)
)
```

#### Track User Registration

```js
tracker.trackUserRegistration(
  unhashedMail, // unhashed email - will be hashed by the function (string)
  gender, // m or f (string)
  ageGroup, // e.g. 25-30 (string)
  zipCode, // (string)
  city, // (string)
  country, // (string)
  extraData // (object)
)
```


#### Recommendation Impression and Click
`trackRecoImpression` and `trackRecoClick` are two methods for tracking the impressions and clicks of user interaction
with recommendation widgets. Each Recommendation API result returns a unique identifier `correlationId`. The widgets
are commonly placed on the page of another article and the concept of `sourceExternalId` is thus the ID of the article
where the recommendation is shown to the user, whereas `targetExternalId` is the ID of the article the recommendation
is attempting to get the user to click on.

```js
tracker.trackRecoImpression(
  correlationId, // Correlation ID (string)
  sourceExternalId, // ID of the page where the recommendations are rendered (string)
  targetExternalIds, // List of recommended IDs (comma separated string)
  widgetType, // Widget type, eg. mehr zum thema, top n, video rec etc. (string)
  widgetLayout // Widget layout, eg. image, image+text, etc. (string)
)
```

```js
tracker.trackRecoClick(
  correlationId, // Correlation ID (string)
  sourceExternalId, // External ID of the page where the recommendations are rendered (string)
  targetExternalId // External ID of the recommended article that was clicked on (string)
)
```


#### Variation Impression and Click
`trackVariationImpression` and `trackVariationClick` are two methods for tracking impressions and clicks of any type of
variation on a page. Variations are any type of difference in for example images, headline or gallery layout shown to
different users.

```js
tracker.trackVariationImpression({
  contentId: '5a832ce1-8962-4f5e-8bc2-2ac5f70141f8',
  contextType: 'teaser-image',
  variationId: 'dfad307a-7b6e-4838-8757-781f34841914'
})
```

```js
tracker.trackVariationClick({
  contentId: '5a832ce1-8962-4f5e-8bc2-2ac5f70141f8',
  contextType: 'teaser-image',
  variationId: 'dfad307a-7b6e-4838-8757-781f34841914'
})
```

#### Opting Out of Tracking
As a mobile app might use a bunch of other trackers in addition to the one described
in this document, we recommend storing user's tracking and privacy preferences in the app's local storage
itself. When our tracker is loaded, a check can be added as shown in the following example.  

```javascript
const hasUserOptedOutOfRingierTracker = false; //<--- store/retrieve this one from user's preferences
if(hasUserOptedOutOfRingierTracker) {
  tracker.optOut();
}
```

When the user opts back in, `optIn` method can be called.

```javascript
tracker.optIn();
```

:warning: Note that the react-native tracker does not maintain the state of opt out when a new instance of tracker is
loaded. Hence we recommend one of the following approaches to respect user's privacy (stored in user's preferences
somewhere in the app) when the user opts out.
* Not load the Ringier tracker at all if the user has opted out.
* Load the tracker but directly after loading it check if the user has opted out by looking at user's preferences. If
the user has opted, out, call `optOut` method directly after initialising the tracker.