Install Optimizely Community API

Setup

Package conventions

The packages of the Optimizely Community API adhere to a number of conventions intended to enhance their discoverability and clarify their purposes. A description of these conventions can be found below.

Package identification

Packages comprising the Optimizely Community API are identified with the prefix EPiServer.Social.

Feature packages

Specific feature packages are identified by a name conforming to the following pattern: EPiServer.Social.[Feature-Name]. The [Feature-Name] identifies the platform feature being installed with the package. Examples:

• EPiServer.Social.Comments
• EPiServer.Social.Ratings

Integration packages

Each Optimizely Community API feature package is accompanied by an optional Optimizely Content Management System (CMS) integration package. These packages conveniently register the services of an Optimizely Community API feature with the service locator supporting an CMS site. These packages can be identified by a name conforming to the following pattern: EPiServer.Social.[Feature-Name].Site. Examples:

• EPiServer.Social.Comments.Site
• EPiServer.Social.Ratings.Site

Package list

Here are the Optimizely Community API packages.

The following packages support the platform services and are ancillary to the packages above.

Install

Follow these steps to install the Optimizely Community API packages. These steps may be repeated for each feature.

• Installing in an Optimizely site
• Installing in other applications

Install in an Optimizely site

1. Open the Optimizely site with Visual Studio.
2. From Visual Studio's Solution Explorer window, right click the website's project.
3. From the menu, choose Manage NuGet Packages.
4. From the NuGet Package Manager, select the Package Source serving the Optimizely Community API packages.
5. From the list of packages, click the EPiServer.Social.[Feature-Name].Site package corresponding to the feature that you wish to install.
6. Click the Install button. When complete, the package and its dependencies are applied to your site.

Install in other applications

1. Open the application with Visual Studio.
2. From Visual Studio's Solution Explorer window, right click the website's project.
3. From the menu, choose Manage NuGet Packages.
4. From the NuGet Package Manager, select the Package Source serving the Optimizely Community API packages.
5. From the list of packages, click the EPiServer.Social.[Feature-Name] package corresponding to the feature that you wish to install.
6. Click the Install button. When complete, the package and its dependencies are applied to your site.

Get connected

To use the Optimizely Community APIs, you must first configure your application to communicate with the cloud services that support these features.

📘

Note

The details of this configuration are provided to you when your Optimizely Community API account is provisioned. If you have not received your configuration, please contact your Optimizely account manager.

CMS 12 – Configure the Optimizely Community API

Open appsettings.json and update it to include the XML configuration that was provided to you. An example configuration is shown below:

{
  “EPiServer”: {
    "SocialOptions": {
      "settings": {
        "TimeOut": "100000"
      },
      "authentication": {
        "appId": "appId",
        "secret": "supersecr"
      },
      "endpoints": {
        "ActivityStreams": https://change.me/,
        "Comments": https://change.me/,
        "Groups": https://change.me/,
        "Moderation": https://change.me/,
        "Ratings": https://change.me/
      }
    },
  }
}

Add the service into the in Startup.cs file

services.AddSocialCommon();
services.AddSocialFramework();

CMS 11 – Configure the Optimizely Community API

Open your application's web.config or app.config and update it to include the XML configuration that was provided to you. An example configuration is shown below:

<configuration>
  <configSections>
    <section name="episerver.social" type="EPiServer.Social.Common.Rest.Configuration.SocialConfiguration, EPiServer.Social.Common.Rest.Configuration"/>
  </configSections>
  <episerver.social>
    <settings timeout="100000"/>
    <authentication appId="your-application-id" secret="your-application-secret"/>
    <endpoints>
      <add name="Comments" value="https://..." />      
      <add name="Ratings" value="https://..." />      
      <add name="Moderation" value="https://..." />      
      <add name="ActivityStreams" value="https://..." />      
      <add name="Groups" value="https://..." />      
    </endpoints>
  </episerver.social>
</configuration>

📘

Note

This XML represents a sample configuration. The configuration provided to you contains the necessary data to connect to the Optimizely Community API cloud services.

📘

Note

A missing or malformed configuration will result in a SocialException being thrown when attempting to interact with the Optimizely Community APIs.

Settings

This section captures general settings for the Optimizely Community APIs.

• timeout – The length of time (in milliseconds), which the Optimizely Community APIs will allow for requests to complete. Requests that exceed the configured timespan are aborted with an exception.

Authentication

This section captures the settings necessary for your application to authenticate with the Optimizely Community API.

• appId – The unique identifier representing your Optimizely Community API account.
• secret – The cryptographic key used to ensure the authenticity of requests from your application.

Endpoints

This section defines the endpoints for individual Optimizely Community API services.

Authentication

The Optimizely Community API uses a multi-layered approach to ensuring the authenticity and integrity of each request issued to it.

Configuration

The Optimizely Community API configuration for your application captures settings supporting the authentication process. The accuracy of these settings is crucial. Inaccurate authentication settings result in requests being rejected as unauthentic.

📘

Note

Your application’s appId and secret are private to your application. This information should not be committed to a source control repository or otherwise publicly exposed. It is recommended that this information be applied as a step in your application deployment process.

Server Time

One aspect of the authentication procedure enforces an expiration time for all requests. A request to the Optimizely Community API is allowed five minutes from the time it is constructed until the time it is received by the platform. Requests falling outside of this grace period are rejected as unauthentic.

📘

Note

It is essential that the server hosting your application maintains accurate time. When the server time is inaccurate, requests are created with inaccurate timestamps. As a result, these requests may be rejected as unauthentic.

Communicate with cloud services

The Optimizely Community APIs communicate with cloud services over HTTPS. The endpoints for these services are identified in the configuration for your application. Configure your application hosting environment to permit communication between your application and these endpoints.