@ringierag/ringier-pixel-react-native

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:

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:

let tracker = new RingierTracker('unique-app-id');

You can register an error handler in case something goes wrong:

tracker.onError((err) => {
  console.log(err);
});

Tracking API

Page View

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.

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

Enabling page pings as below will send pings in the background.

tracker.enablePagePings();

Then track page views as normal on each page.

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.

tracker.disablePagePings();

Set UserId

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

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

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.

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)
)

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.

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

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.

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.

tracker.optIn();

⚠️ 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.