Install Optimizely Community API

Setup

Package conventions

The packages of the Optimizely Community API adhere to several 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 a 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.

• EPiServer.Social.Framework – Installs features of the Optimizely Community API to an Optimizely Content Management System (CMS) site
• EPiServer.Social.Comments – Installs the platform's commenting services
• EPiServer.Social.Comments.Site – Integrates the platform's commenting services with the CMS's service locator
• EPiServer.Social.Ratings – Installs the platform's rating services
• EPiServer.Social.Ratings.Site – Integrates the platform's rating services with the CMS's service locator
• EPiServer.Social.Moderation – Installs the platform's moderation services
• EPiServer.Social.Moderation.Site – Integrates the platform's moderation services with the CMS's service locator
• EPiServer.Social.Groups – Installs the platform's group services
• EPiServer.Social.Groups.Site – Integrates the platform's group services with the CMS's service locator
• EPiServer.Social.ActivityStreams – Installs the platform's activity stream services
• EPiServer.Social.ActivityStreams.Site – Integrates the platform's activity stream services with the CMS's service locator

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

• EPiServer.Social.Common – Supports core functionality of the platform's services
• EPiServer.Social.Common.Rest – Supports integration between the platform's features and associated cloud services

Install

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

• Install in an Optimizely site
• Install 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. Select the Package Source serving the Optimizely Community API packages from the NuGet Package Manager.
5. From the list of packages, click the EPiServer.Social.[Feature-Name].Site package corresponding to the feature that you want to install.
6. Click Install. 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. Select the Package Source serving the Optimizely Community API packages from the NuGet Package Manager.
5. From the list of packages, click the EPiServer.Social.[Feature-Name] package corresponding to the feature that you want to install.
6. Click Install. 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.

Netcore web application – without CMS integration

Open appsettings.json and update it to include the XML configuration provided to you. The following code sample shows an example configuration.

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

Add and initialize the services in the startup processing.

using EPiServer.Social.Common;
using EPiServer.Social.Framework;
...
builder.Services.AddSingleton<ANY-CUSTOM-ACTIVITY-PROCESSORS>();
builder.Services.AddSocialFramework();
builder.Services.Replace(ServiceDescriptor.Singleton<ISocialLogger, <YOUR-LOGGER>());
 
var app = builder.Build();
app.Services.InitializeActivityStreams();

CMS 12 – Configure the Optimizely Community API

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

{
  "EPiServer": {
    "SocialOptions": {
      "settings": {
        "TimeOut": "100000"
      },
      "authentication": {
        "appId": "appId",
        "secret": "supersecret"
      },
      "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 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) the Optimizely Community APIs will allow 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 ensure the authenticity and integrity of each request issued to it.

Configuration

Your application's Optimizely Community API configuration 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 requests. A request to the Optimizely Community API is allowed five minutes from the time it is constructed until the platform receives it. 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. Your application's endpoints are identified in its configuration. Configure your application hosting environment to permit communication between your application and these endpoints.