Rakuten Mission SDK - JS SDK

Reward Mission JS SDK is a javascript SDK for integrating with Reward Mission functionalities to let users get Rakuten Points as the reward of achieving missions.

Table of Contents

• Prerequisites
• Installation
• Initialize Mission SDK
• Get User Information
• API Reference
• FAQ
• UI
• CHANGELOG

Prerequisites

Browser Support

Mission JS SDK uses Native Browser fetch to connect and fetch data from the API. That's why Mission JS SDK supports below browsers:

| Browser | Version | Year | | ------- | ------- | ---- | | Chrome | > 42 | 2015 | | Edge | > 14 | 2016 | | Safari | > 10.1 | 2017 | | Firefox | > 39 | 2015 |

*reference: fetch browsers supported

If you want to support older browsers, please provide and import the fetch polyfills in your websites.

Front End Framework

Mission JS SDK doesn't use any Front End Framework (e.g. React, Vue, etc) to render and display the UI. But only uses Vanilla Javascript DOM manipulation. There shouldn't be any issue or conflict with your website's tech stack.

Users Have to Logged In to Rakuten

Mission JS SDK requires users to logged in to Rakuten Auth first before being able to use SDK features. For handing the authentication, please refer to this Authentication guideline.

Languages Supported

Mission SDK supports 2 languages: ja (japanese) & en (english), but ja is the default language. You can set the language to be used during the Mission SDK init Initialize Mission SDK.

Responsive UI

Mission SDK supports both Desktop & Mobile website by reading the device's width and height viewport. Mission SDK will display UI (Notification Banner, SDK Portal, etc) depends on the user's platform automatically.

• Mobile: width <= 768px
• Desktop: width > 768px

Installations

Import file via script tag

To install via script, import our JS SDK file by pasting the following <script> tag inside the <header> tag.

Source file: https://portal.reward.rakuten.co.jp/sdk-static/sdk/{{VERSION}}/missionsdk.js

Latest version: https://portal.reward.rakuten.co.jp/sdk-static/sdk/1.2.0/missionsdk.js

<header>
  // ... put this before the end of header tag
  <script
    type="text/javascript"
    src="https://portal.reward.rakuten.co.jp/sdk-static/sdk/1.2.0/missionsdk.js"
  ></script>
</header>

After pasting the script, Mission SDK JS will be available and can be accessed in the window object, through the RewardMissionSDK variable.

<script>
  const rewardSDK = window.RewardMissionSDK || {};
</script>

Import package from npm

To install via npm, you can install the package directly via the command:

# With npm
npm install rakutenreward-js

The current package version is 1.3.0 (There are no changes with 1.2.0)

After installing the package, Mission SDK can be imported like this:

import RewardMissionSDK from 'rakutenreward-js';

RewardMissionSDK.init({
  // Input app key
});

Click here to see an example of how to implement it in React: I want to use RewardSDK in the React environment. How can I do that?

Initialize Mission SDK

To use Mission SDK, you need to call our init function and pass the Application Key value for your website, given by Reward SDK team.

const rewardSDK = window.RewardMissionSDK || {};

rewardSDK.init({
  appKey: 'QWERTYUIOPASDFGHJKLZXCVBNM123456789',
  language: 'ja',
});

• Note, passing language is Optional. If you don't pass it, then SDK will use the browser's language setting, default to Japanese (ja).

| function | async | parameters | response type | description | | -------- | ----- | --------------------------------------- | ------------- | ---------------------- | | init | Yes | SDKInitParams | void | Initialize Mission SDK |

The init function can receives multiple parameters, depends on your needs. Please visit this SDKInitParams API Reference.

If you want to do something after the initialization, there are 2 ways:

1. Pass the codes inside successCallback

rewardSDK.init({
  appKey: 'QWERTYUIOPASDFGHJKLZXCVBNM123456789',
  language: 'ja',
  successCallback: async () => {
    const isSignedIn = await rewardSDK.hasUserSignedIn();
    console.log('isSignedIn', isSignedIn);
  },
});

2. Use async/await and put the codes sequentially

(async () => {
  try {
    await rewardSDK.init({
      appKey: 'QWERTYUIOPASDFGHJKLZXCVBNM123456789',
      language: 'ja',
    });
  } catch (err) {
    // to catch init/authentication error
  }

  const isSignedIn = await rewardSDK.hasUserSignedIn();
  console.log('isSignedIn', isSignedIn);
})();

Authentication

There are two auth mechanisms provided by Mission JS SDK:

1. SDK handles the login. This authentication can be used if:

   • Not internal Rakuten's websites
   • Haven't used Rakuten OMNI Auth
   • Don't have access to Tokens generated by Rakuten OMNI
   • Don't want to share the same login state with SDK

2. You handle the login, and pass the login state to SDK. This authentication can be used if:

   • You already used Rakuten OMNI Auth, and can acquire Refresh Token and Access Token to access RWDSDK API
   • You want the users to keep the login state in Mission SDK, without logging in again

SDK handles the login

Mission SDK can handles the auth and login via Rakuten OMNI. This one will require users to re-login to Rakuten OMNI.

We provide several ways to login into Rakuten OMNI:

1. Redirect User to Rakuten OMNI to login.

rewardSDK.openLoginUrl(); // calling this function will redirect users to login page

2. Get Rakuten OMNI's Login URL and handle the redirection by yourself. This one is useful if you want to display the login button or components by yourself.

const loginUrl: string = rewardSDK.getLoginUrl(); // calling this function will return login URL and redirect users back to the current page
window.location.href = loginUrl;

3. Display our default Login Button. But, you need to prepare the html div tag (and define the id property) as a placeholder for our Login Button element.

const elementId = 'sdk-login-button-element-id';
rewardSDK.displayLoginButton(elementId); // calling this function will fill the 'sdk-login-button-element-id' element with SDK Login Button

Pass the Login State to SDK

In order to use your existing API-C Tokens to connect with Mission JS SDK, you have to apply your API-C client to our scope. If you already have an Access Token from Rakuten OMNI and want to keep the login state between your website and Mission SDK, you can pass the Access Token when initializing the SDK.

To use this feature and to make sure all the functionalities work (including refresh access token when expired), you have to pass the accessToken data during the Mission SDK initialization, and pass the tokenType omni. Please see the init function's parameters here SDKInitParams.

rewardSDK.init({
  appKey: 'QWERTYUIOPASDFGHJKLZXCVBNM123456789',
  language: 'ja',
  tokenType: 'omni',
  accessToken: 'QWERTYUIOPASDFGHJKLZXCVBNM123456789',
  userName: 'John Doe',
});

Notes:

1. Make sure that your accessToken has access to RWDSDK API in API-C.
2. If your token type is from omni, then you need to pass it.
3. Passing userName is optional, and will be used to display the User's Name in Mission SDK Portal.

Get User Information

Get Login Status

await rewardSDK.hasUserSignedIn(): Boolean

| function | async | parameters | response type | description | | --------------- | ----- | ---------- | ------------- | ----------------------------------- | | hasUserSignedIn | yes | no | boolean | User's login status (true or false) |

Usage Example:

// async/await supported
const isSignedIn = await rewardSDK.hasUserSignedIn();

// Promise-based
rewardSDK.hasUserSignedIn().then((isSignedIn) => {
  console.log(isSignedIn);
});

Get User's Full Name

rewardSDK.getUserName(): String

| function | async | parameters | response type | description | | ----------- | ----- | ---------- | ------------- | ------------------------------- | | getUserName | no | no | string | User's full name (ex. John Doe) |

Usage Example:

const userFullName = rewardSDK.getUserName();

Get User's Point Information

await rewardSDK.getUserInfo(): UserPointInformation

| function | async | parameters | response type | description | | ----------- | ----- | ---------- | ----------------------------------------------------- | ------------------------ | | getUserInfo | yes | no | UserPointInformation | User's point information |

Usage Example:

// async/await supported
const userPointInformation = await rewardSDK.getUserInfo();

// Promise-based
rewardSDK
  .getUserInfo()
  .then((userPointInformation) => {
    const { unclaimedPoints, currentPoints } = userPointInformation;
  })
  .catch((err) => {
    // failed to get user points info
  });

Log Out

rewardSDK.logout(options?: SDKCallbackParams): Void

| function | async | parameters | response type | description | | -------- | ----- | ---------------------------------------------------------- | ------------- | ----------- | | logout | yes | SDKCallbackParams (Optional) | void | No response |

Usage Example:

rewardSDK.logout();

// with callback
const successCallback = () => console.log('Log out success!');
rewardSDK.logout({ successCallback });

Start Session or Refresh Access Token

rewardSDK.startSession(options?: SDKCallbackParams): UserPointInformation

| function | async | parameters | response type | description | | ------------ | ----- | ---------------------------------------------------------- | ------------- | ------------------------------------------------------------ | | startSession | yes | SDKCallbackParams (Optional) | void | Return UserPointInformation |

Usage Example:

// async/await supported
const userInformation = await rewardSDK.startSession();

// Promise-based
rewardSDK.startSession().then((userPointInformation) => {
  // do something
});

// with callback
const successCallback = (userInformation: UserPointInformation) =>
  console.log('Start Session success!');
rewardSDK.startSession({ successCallback });

Mission Achievement

Get Mission List

rewardSDK.getMissions(options?: SDKCallbackParams): MissionItem[]

| function | async | parameters | response type | description | | ----------- | ----- | ---------------------------------------------------------- | ------------------------------------- | -------------------- | | getMissions | yes | SDKCallbackParams (Optional) | MissionItem[] | List of Mission Item |

Usage Example:

// async/await supported
const missionList = await rewardSDK.getMissions();

// Promise-based
rewardSDK
  .getMissions()
  .then((missionList) => {
    console.log(missionList);
  })
  .catch((err) => {
    // failed to get mission list
  });

// with callback
const successCallback = () => console.log('Get Mission List success!');
rewardSDK.getMissions({ successCallback });

Get Mission List Lite

rewardSDK.getMissionsLite(options?: SDKCallbackParams): MissionItem[]

| function | async | parameters | response type | description | | ----------- | ----- | ---------------------------------------------------------- | ------------------------------------- | -------------------- | | getMissionsLite | yes | SDKCallbackParams (Optional) | MissionItem[] | List of Mission Item without Progress |

Usage Example:

// async/await supported
const missionList = await rewardSDK.getMissionsLite();

// Promise-based
rewardSDK
  .getMissionsLite()
  .then((missionList) => {
    console.log(missionList);
  })
  .catch((err) => {
    // failed to get mission list
  });

// with callback
const successCallback = (missionLiteList) => console.log('Get Mission List success!', missionLiteList);
rewardSDK.getMissionsLite({ successCallback });

Get Mission Details

This returns the specific mission given the action code, including the progress.

rewardSDK.getMissionDetails(missionActionData: MissionActionData, options?: SDKCallbackParams): MissionItem;

Usage Example:

// async/await supported
const missionDetails = await rewardSDK.getMissionDetails({ actionCode: 'ABCDEFGH123' });

// Promise-based
rewardSDK
  .getMissionDetails({ actionCode: 'ABCDEFGH123' })
  .then((missionDetail) => {
    console.log(missionDetail);
  })
  .catch((err) => {
    // failed to get mission list
  });

// with callback
const successCallback = (missionDetails) => console.log('Get Mission Details success!', missionDetails);
rewardSDK.getMissionDetails({ actionCode: 'ABCDEFGH123' }, { successCallback });

Log Action

To log action, you need to call Log Action API.

rewardSDK.logAction(missionActionData: MissionActionData, options?: SDKCallbackParams): MissionCompleteResponse

| function | async | parameters | response type | description | | --------- | ----- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------- | | logAction | yes | (MissionActionData, SDKCallbackParams: [Optional]) | MissionCompleteResponse | Return Mission Achievement Complete Information |

Usage Example:

// async/await supported
await rewardSDK.logAction({ actionCode: 'ABCDEFGH123' });

// Promise-based
rewardSDK
  .logAction({ actionCode: 'ABCDEFGH123' })
  .then((achieveMissionResponse) => {
    console.log(achieveMissionResponse);
  })
  .catch((err) => {
    // failed to get achieve mission
  });

// with callback
const successCallback = () => console.log('Log Action success!');
rewardSDK.logAction({ actionCode: 'ABCDEFGH123' }, { successCallback });

After achieving the mission, Notification Banner UI will be displayed. Mission SDK provides several types of Notification Banner:

1. MODAL (No Ads)

2. BANNER (No Ads)

3. BANNER_50 (With 50px heigth Ads)

4. BANNER_250 (With 250px heigth Ads)

5. CUSTOM

You can create your own notification UI after achieving mission by calling your function after receiving the response from logAction function.

// async/await supported
const achieveMissionResponse = await rewardSDK.logAction({ actionCode: 'ABCDEFGH123' });
displayNotification(achieveMissionResponse);

// Promise-based
rewardSDK
  .logAction({ actionCode: 'ABCDEFGH123' })
  .then((achieveMissionResponse) => {
    displayNotification(achieveMissionResponse);
  })
  .catch((err) => {
    // failed to achieve mission
  });

Join and Cancel Mission

From version 1.1.0 onwards, we support the join and cancel functionality for missions.

There are no code changes required and this feature can be enabled in the developer portal during mission creation.

Set needsSubscription to Yes

During mission creation in the developer portal, set the Does this mission require user's subscription parameter to 'Yes'. This step is essential to activate the join and cancel feature.

Terms and Conditions

Once needsSubscription is set to 'Yes', a terms and conditions field will automatically appear. Fill in the necessary details in this field.

Joining and Exiting Missions

With needsSubscription set to 'Yes' and the terms and conditions filled, users can then join and exit missions. The terms and conditions will be displayed during the join process.

Persistent Progress

If a user exits a mission and later decides to join the same mission again, their progress will be retained.

Claim Point

Get Unclaimed Point List

rewardSDK.getUnclaimedItems(options?: SDKCallbackParams): UnclaimedItem[]

| function | async | parameters | response type | description | | ----------------- | ----- | ---------------------------------------------------------- | ----------------------------------------- | ---------------------- | | getUnclaimedItems | yes | SDKCallbackParams (Optional) | UnclaimedItem[] | List of Unclaimed Item |

Usage Example:

// async/await supported
const unclaimedItems = await rewardSDK.getUnclaimedItems();

// Promise-based
rewardSDK
  .getUnclaimedItems()
  .then((unclaimedItems) => {
    console.log(unclaimedItems);
  })
  .catch((err) => {
    // failed to get unclaimed items
  });

// with callback
const successCallback = () => console.log('Get Unclaimed Items success!');
rewardSDK.getUnclaimedItems({ successCallback });

Claiming Point

rewardSDK.claimPointMission(pointActionData: PointActionData, options?: SDKCallbackParams): ClaimPointResponse

| function | async | parameters | response type | description | | ----------------- | ----- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------- | | claimPointMission | yes | (PointActionData, SDKCallbackParams (Optional)) | ClaimPointResponse | Claim Point Response |

Usage Example:

// async/await supported
const response = await rewardSDK.claimPointMission({
  actionCode: 'ABCDEFG123',
  achievedDateStr: '20231231',
});

// Promise-based
rewardSDK
  .claimPointMission({
    actionCode: 'ABCDEFG123',
    achievedDateStr: '20231231',
  })
  .then((claimPointResponse) => {
    console.log(claimPointResponse);
  })
  .catch((err) => {
    // failed to claim point
  });

// with callback
const successCallback = () => console.log('Claim Point success!');
rewardSDK.claimPointMission(
  {
    actionCode: 'ABCDEFG123',
    achievedDateStr: '20231231',
  },
  { successCallback }
);

Points

Getting Point History

rewardSDK.getPointHistory(options?: SDKCallbackParams): PointHistory[]

| function | async | parameters | response type | description | | --------------- | ----- | ---------------------------------------------------------- | --------------------------------------- | ------------------------------------------ | | getPointHistory | yes | SDKCallbackParams (Optional) | PointHistory[] | List of Point History in the last 3 months |

Usage Example:

// async/await supported
const pointsHistory = await rewardSDK.getPointHistory();

// Promise-based
rewardSDK
  .getPointHistory()
  .then((pointsHistory) => {
    console.log(pointsHistory);
  })
  .catch((err) => {
    // failed to get points history
  });

// with callback
const successCallback = () => console.log('Get Points History success!');
rewardSDK.getPointHistory({ successCallback });

Getting Current Points

rewardSDK.getCurrentPoints(options?: SDKCallbackParams): CurrentPoints[]

| function | async | parameters | response type | description | | ---------------- | ----- | ---------------------------------------------------------- | -------------------------------------- | ------------- | | getCurrentPoints | yes | SDKCallbackParams (Optional) | CurretPoints | Current Point |

Usage Example:

// async/await supported
const currentPoints = await rewardSDK.getCurrentPoints();

// Promise-based
rewardSDK
  .getCurrentPoints()
  .then((currentPoints) => {
    console.log(currentPoints);
  })
  .catch((err) => {
    // failed to get current points
  });

// with callback
const successCallback = () => console.log('Get Current Points success!');
rewardSDK.getCurrentPoints({ successCallback });

Open Reward SDK Portal

Opening Reward Portal

rewardSDK.displaySDKPortal(tab?: String, options?: SDKCallbackParams): Void

| function | async | parameters | response type | description | | ---------------- | ----- | ------------------------------------------------------------------------------------------------------------------------- | ------------- | ---------------------- | | displaySDKPortal | no | (tab: ('home', 'mission', 'unclaimed', 'poikatsu', 'more'), SDKCallbackParams (Optional)) | Void | Open Reward SDK Portal |

Usage Example:

rewardSDK.displaySDKPortal();

Mission SDK User's Consent (Optional)

Mission JS SDK provides optional user's consent feature for Reward SDK's terms of use and privacy policy before they can access any Reward SDK features. It's up to each publishers if you want to enable this feature or not.

If user consent feature is enabled, users are required to give their consent when doing these:

• Open Reward SDK Portal
• Log Action
• Claim Point

User Consent popup will be displayed before they can complete above tasks if the users are still not consent yet.

Get User Consent Status

rewardSDK.getIsUserConsent(): Boolean

| function | async | parameters | response type | description | | ---------------- | ----- | ---------- | ------------- | --------------------- | | getIsUserConsent | no | no | boolean | User's Consent Status |

Usage Example:

const isUserConsent = rewardSDK.getIsUserConsent(); // true or false

Accept User Consent

rewardSDK.acceptConsent(options?: SDKCallbackParams): Void

| function | async | parameters | response type | description | | ------------- | ----- | ---------------------------------------------------------- | ------------- | ------------------- | | acceptConsent | yes | SDKCallbackParams (Optional) | void | Accept User Consent |

Usage Example:

const successCallback = () => console.log('Accept Consent success!');
rewardSDK.acceptConsent({ successCallback });

Open User Consent's Popup

rewardSDK.displayConsentPopup(options?: SDKCallbackParams): Void

| function | async | parameters | response type | description | | ------------------- | ----- | ---------------------------------------------------------- | ------------- | ------------------------- | | displayConsentPopup | yes | SDKCallbackParams (Optional) | void | Open User Consent's Popup |

Usage Example:

const successCallback = () => console.log('Open Consent Popup success!');
rewardSDK.displayConsentPopup({ successCallback });