Installera Optimizely-integrationen (version 12)

Integrationen gör att webbredaktörer får direkt åtkomst till filer och mappar från Mediaflow inuti Optimizely 12-gränssnittet och kan bädda in bilder i på-sidan-redigering, i block eller i textredigeraren (TinyMCE). Den gör det också möjligt att bädda in video från Mediaflow med Mediaflows mediespelare. 

Integrationen kopplar direkt mellan Optimizely 12-webbservern och Mediaflow-servrarna, vilket gör att filer inte behöver laddas ner lokalt först när bilder monteras.

Bra att veta

För prestanda och stabilitet kopieras monterade bilder alltid till webbservern (under "Sidfiler" eller "Globala filer" i Optimizely 12). Din webbplats är därmed inte beroende av Mediaflow, och integrationen påverkar inte prestandan för vanliga sidvisningar. Alla monterade bilder finns kvar i Optimizely och inga ändringar på webbplatsen krävs om du avinstallerar integrationen.

Systemkrav

Kontrollera att miljön uppfyller följande innan du installerar:

• .NET 8 (net8.0)
• Optimizely CMS 12 – kompatibel med EPiServer.CMS.UI.Core version 12.17.1 eller senare (under version 13)
• Ett Mediaflow-konto med minst en serverkey konfigurerad
• Behörighet att lägga till NuGet-paket och ändra webbplatsens konfiguration (appsettings.json, Startup.cs eller Program.cs)

Integrationen fungerar både på självhostad Optimizely CMS 12 och på Optimizely DXP. Inloggning med Opti ID stöds från version 1.2.5, se Opti ID (SSO). För DXP-specifik konfiguration (hemligheter, miljötransformer, deployment), se avsnittet Installera på Optimizely DXP längre ned.

Integrationen distribueras som NuGet-paketet Mediaflow.Optimizely på Optimizelys NuGet-feed.

Inställningar i Mediaflow

Integrationen kan användas så snart den är installerad. Men för att filerna ska vara tillgängliga och kunna användas optimalt behöver administratörer först ha förberett inställningarna i Mediaflow.

Varje serverkey är en Mediaflow OAuth refresh token. Du hämtar den i Mediaflow under Inställningar > Integrationer > EPiServer/Optimizely – nyckeln ligger i fältet Refresh token. Nyckeln avgör vilka Mediaflow-resurser användaren får åtkomst till. Med virtuell rollmappning (rekommenderas) kan du tilldela olika nycklar till olika redaktörsgrupper.

Du behöver rätt behörighet för att se integrationsinställningarna. Om de inte är tillgängliga kan du gå in i superadmin-läge eller kontakta en Mediaflow-administratör i din organisation.

Installera integrationen

Steg 1 – Lägg till NuGet-feed och hitta paketet

Mediaflows integration installeras som ett vanligt NuGet-paket. Optimizely har en egen NuGet-feed som behöver läggas till för att paketet ska hittas. Instruktioner finns här: https://nuget.optimizely.com/feed/

När feeden är tillagd kan du söka efter integrationen i Visual Studio på Mediaflow.Optimizely. Mer information och senaste version finns på Optimizelys paketsida: https://nuget.optimizely.com/packages/mediaflow.optimizely/

Steg 2 – Installera NuGet-paketet

Använd Optimizelys vanliga NuGet-installation, eller installera från kommandoraden:

dotnet add package Mediaflow.Optimizely --version [önskad version]

Steg 3 – Konfigurera i appsettings.json

All konfiguration sker i appsettings.json och i Startup.cs (eller Program.cs). Lägg till en Mediaflow-sektion i appsettings.json med din serverkey och de valbara alternativ du vill anpassa.

{
  "Mediaflow": {
    "EnableMediaLibraryUpload": true,
    "LimitEmbedType": "javascript",
    "ForceAltText": true,
    "SaveLocation": "page",
    "VirtualRoleMapping": [
      {
        "VirtualRole": "*",
        "ServerKey": "<din-mediaflow-serverkey>"
      }
    ]
  }
}

Inställningsreferens

Key och ServerKey

Värdet ServerKey i VirtualRoleMapping är din Mediaflow OAuth refresh token. Mediaflow rekommenderar VirtualRoleMapping med en "*"-rad för en gemensam nyckel, eller separata rader per roll när du behöver segmentera innehåll (se Segmentera innehåll med rollmappning).

SaveLocation

Styr var bilder sparas i Optimizelys mediasektion. Observera att bilder alltid kopieras till webbservern oavsett val.

Steg 4 – Registrera integrationen i Startup.cs

Två registreringsanrop är obligatoriska: AddMediaflow() och UseMediaflow(). Admin-sidan /mediaflow/settings är förkompilerad och kräver inte Razor runtime compilation. Lägg till AddMediaflowViews() om webbplatsen använder Mediaflows paketerade visningsmallar – det rekommenderas om ni använder TinyMCE, eftersom det är visningsmallen som håller bildernas alt-text, beskrivning och fotograf uppdaterade på den publicerade sidan. Lägg till dem i Startup.cs eller motsvarande i din Program.cs.

ConfigureServices

Välj alternativet som passar din webbplats.

Minsta registrering

using EPiServer.Cms.TinyMce.Core;
using Mediaflow.Optimizely;

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddCms()
        // ... övriga Optimizely-tjänster ...
        .AddMediaflow();

    // Valfritt: paketerade visningsmallar (rekommenderas med TinyMCE)
    // services.AddCms().AddMediaflow().AddMediaflowViews();

    // Valfritt: aktivera Mediaflow-knappen i TinyMCE (se artikel 2)
}

Alternativ B – webbplatsen aktiverar redan Razor runtime compilation

Behåll ditt befintliga anrop och lägg Mediaflows view-stöd efter det (gäller bara om ni använder visningsmallarna):

using EPiServer.Cms.TinyMce.Core;
using Mediaflow.Optimizely;

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddCms()
        // ... övriga Optimizely-tjänster ...
        .AddMediaflow();

    services.AddControllersWithViews().AddRazorRuntimeCompilation();

    // Mediaflow-stöd för visningsmallar – efter runtime compilation!
    services.AddMediaflowViews();
}

Configure (request pipeline)

Lägg UseMediaflow() efter UseAuthorization() och före UseEndpoints():

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseStaticFiles();
    app.UseRouting();
    app.UseAuthentication();
    app.UseAuthorization();

    app.UseMediaflow();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapContent();
    });
}

Vad varje anrop gör

Steg 5 – Sätt behörigheter

Mediaflow är inte öppet för alla grupper i Optimizely, för att begränsa åtkomst och förhindra obehörig användning av Mediaflow.

Tillåtna grupper är CmsEditors, CmsAdmins, WebEditors, WebAdmins, Administrators samt gruppen Mediaflow, som du kan skapa och lägga medlemmar i för att ge dem åtkomst.

Add-onet slår upp en Mediaflow-serverkey för aktuell användare via VirtualRoleMapping. Om ingen mappning matchar används reservnyckeln Key för användare i rollerna ovan. Om varken mappning eller Key finns kan användaren inte autentisera mot Mediaflow. Användaren måste alltid vara inloggad i CMS – även med en "*"-rad.

Använder webbplatsen Opti ID: mappa mot CmsEditors och CmsAdmins (eller "*") i stället för de äldre rollerna WebAdmins/WebEditors. Egna roller i VirtualRoleMapping måste finnas i Opti ID Admin Center (eller er IdP) och synkas till CMS vid inloggning. Mappar ni CMS-virtuella roller, sätt SupportsClaims: true på dem i appsettings.json.

Se till att redaktörer som ska använda väljaren tillhör en roll med matchande VirtualRoleMapping-rad, eller lägg dem i gruppen Mediaflow och konfigurera en lämplig nyckel.

Segmentera innehåll med rollmappning (valfritt)

Som standard kommer alla användare i Optimizely 12 åt samma delade innehåll när bilder monteras – om inte virtuell rollmappning konfigureras. Har du flera redaktörsgrupper som arbetar med olika delar av webbplatsen kan du segmentera innehållet så att grupper får åtkomst till olika Mediaflow-mappar. Detta görs med Optimizelys Virtual Role och VirtualRoleMapping i appsettings.json.

Obs: Segmentering på detta sätt kräver en unik serverkey i Mediaflow per grupp. Detta kan vara förknippat med en kostnad beroende på ert avtal.

"Mediaflow": {
  "VirtualRoleMapping": [
    { "VirtualRole": "CmsAdmins",  "ServerKey": "ZZXXCCVVBB" },
    { "VirtualRole": "CmsEditors", "ServerKey": "AABBCCDDEE" },
    { "VirtualRole": "*",          "ServerKey": "QQWWEERRTT" }
  ]
}

Add-onet kontrollerar rollmedlemskap i listordning och använder första matchande rad. Placera specifika roller före jokertecknet "*".

Opti ID (SSO)

Från version 1.2.5 fungerar integrationen på webbplatser som loggar in redaktörer med Opti ID. AddMediaflow() upptäcker Opti ID-schemat och lägger till det i Mediaflows behörighetspolicyer. Ordningen mellan AddMediaflow() och AddOptimizelyIdentity() spelar ingen roll, och ingen extra Mediaflow-konfiguration behövs.

services.AddOptimizelyIdentity(useAsDefault: false);
services.AddMediaflow();

Med useAsDefault: false accepterar policyerna både en Opti ID-session och en session från webbplatsens standardinloggning (t.ex. ASP.NET Identity).

Egna policyer (valfritt). Vill du styra roller eller scheman själv kan du skicka in egna policyer. Policyer under Constants.AdminPolicy och Constants.EditorsPolicy skrivs inte över. Ange alla scheman som ska accepteras – anger du bara ett ignoreras övriga.

services.AddMediaflow(authorization =>
{
    authorization.AddPolicy(Constants.AdminPolicy, policy =>
    {
        policy.AddAuthenticationSchemes(OptimizelyIdentityDefaults.SchemeName);
        policy.RequireRole("CmsAdmins");
    });
});

Cookies. Opti ID-cookies (prefix oid-) kräver SameSite=None och Secure. En webbplatsövergripande cookie-policy med Lax eller Strict gör att Mediaflow ser användaren som utloggad och svarar 401. Justera cookie-policyn i webbplatsen (se Felsökning).

Installera på Optimizely DXP

Om din Optimizely CMS 12-webbplats körs på Optimizely DXP är själva add-onet samma NuGet-paket och samma kodregistrering som för en självhostad webbplats. Följ steg 1–4 ovan. Skillnaderna gäller hur du konfigurerar hemligheter per miljö, deployar kodpaketet och säkerställer utgående nätverksåtkomst.

Inkludera paketet i kodpaketet

Lägg till Mediaflow.Optimizely som en vanlig NuGet-referens i ditt CMS-projekt. När du bygger och publicerar ett DXP-kodpaket (.cms.app.*.nupkg) inkluderas add-onet automatiskt. Deploya via ert vanliga DXP-flöde (Integration → Preproduction → Production). Inget separat DXP-specifikt paket eller modulupload krävs.

Konfigurera inställningar per miljö

DXP tillämpar miljöspecifik konfiguration via transform-filer (appsettings.Integration.json, appsettings.Preproduction.json, appsettings.Production.json) som skriver över värden i appsettings.json vid deployment.

Lägg icke-hemliga Mediaflow-inställningar i rätt transform-fil – t.ex. SaveLocation, ForceAltText, LimitEmbedType och strukturen för VirtualRoleMapping (rollnamn utan nycklar):

{
  "Mediaflow": {
    "EnableMediaLibraryUpload": true,
    "LimitEmbedType": "javascript",
    "ForceAltText": true,
    "SaveLocation": "page",
    "VirtualRoleMapping": [
      { "VirtualRole": "*", "ServerKey": "" }
    ]
  }
}

Lämna ServerKey tom i versionshanteringen och fyll i de riktiga värdena via DXP App Settings (se nedan). Se Configuring environments in Optimizely DXP.

Lagra serverkeys som hemligheter

Mediaflows serverkeys är OAuth refresh tokens och måste behandlas som hemligheter. Commita dem aldrig till versionshanteringen.

På DXP lägger du dem via PaaS-portalen → App Settings för respektive miljö. Inställningarna tillämpas vid nästa deployment. Se Manage app settings in Optimizely DXP.

Enklast – en servernyckel:

Rollmappning – åsidosätt enskilda nycklar:

Definiera VirtualRole-namnen i transform-filen; åsidosätt endast ServerKey-värdena i PaaS-portalen. App Settings har företräde framför appsettings.json och transform-filer.

Startup-registrering på DXP

Använd samma registrering som för vilken CMS 12-webbplats som helst. Om din DXP-lösning redan anropar AddCmsCloudPlatformSupport(), behåll det – det ersätter inte Mediaflow-registreringen. Båda krävs:

services
    .AddCms()
    // ... övriga Optimizely-tjänster ...
    .AddMediaflow();   // + .AddMediaflowViews() vid behov, se steg 4

if (!env.IsDevelopment())
{
    services.AddCmsCloudPlatformSupport(configuration);
}

Lägg även app.UseMediaflow() i request-pipelinen som i steg 4. Många DXP-projekt har redan Razor runtime compilation – använd då Alternativ B i steg 4 om ni lägger till visningsmallarna. Använder DXP-lösningen Opti ID, se Opti ID (SSO).

Utgående nätverksåtkomst

CMS-applikationsservern måste nå Mediaflow över HTTPS för autentisering och filoperationer:

• accounts.mediaflow.com – OAuth token-anrop
• api.mediaflow.com – Mediaflow API

Redaktörernas webbläsare laddar även väljarens resurser från mfstatic.com och kan hämta miniatyrer från m.mediaflow.com. Dessa är klientförfrågningar och blockeras inte av DXP:s servernätverk, men annonsblockerare eller företagsproxys på klientdatorer kan störa.

Om väljaren inte laddar eller uppladdningar misslyckas med autentiseringsfel på DXP men fungerar lokalt: bekräfta med Optimizely-support eller ert nätverksteam att utgående trafik till ovanstående endpoints är tillåten från CMS App Service.

Admin-inställningar och databaser

Det inbyggda admin-gränssnittet på /mediaflow/settings lagrar överstyrningar i Optimizelys Dynamic Data Store, som ligger i miljöns SQL-databas. Inställningar som ändras i Integration förs inte över till Production – konfigurera varje miljö separat, eller använd App Settings och transform-filer för en konsekvent baslinje per miljö.

Verifiera installationen

Efter omstart av webbplatsen:

1. Öppna webbläsarens utvecklarkonsol inloggad i CMS. Bekräfta att det inte finns några 404-fel för sökvägar under /EPiServer/Mediaflow.Optimizely/.
2. Logga in som CMS-redaktör och öppna en sida med en Mediaflow-property eller ett TinyMCE-fält. Bekräfta att Mediaflow-väljaren eller knappen visas.
3. Som administratör (CmsAdmins, WebAdmins eller Administrators – även via Opti ID), öppna /mediaflow/settings och bekräfta att admin-sidan laddas. Här kan du i körläge åsidosätta ForceAltText, VirtualRoleMapping och FileTypeFilter; sparade värden har företräde framför appsettings.json.
4. Opti ID: logga in via Opti ID och öppna Mediaflow-väljaren. Om /api/mediaflow/settings svarar 401 för en inloggad användare, se Felsökning.

Uppgradera från en äldre version

Vid uppgradering från 1.1.x till 1.2.x: bygg om Optimizelys länkdatabas eller spara om innehåll som använder Mediaflow-properties efter uppgraderingen. Version 1.2.x spårar innehållsreferenser (soft links) för Mediaflow-properties, vilket driver References-vyn i Optimizely. Befintligt innehåll indexeras inte automatiskt förrän länkdatabasen byggts om eller berörda sidor och block sparats om.

Till 1.2.5: Har ni lagt till AddMediaflowViews() enbart för admin-sidan kan det tas bort. Behåll det om ni använder TinyMCE, så att metadata på infogade bilder följer mediaobjektet. Har webbplatsen en egen Views/Shared/DisplayTemplates/XhtmlString.cshtml, rendera via Mediaflows tillägg:

@using Mediaflow.Optimizely.Utility
@model EPiServer.Core.XhtmlString
@{ Html.RenderXhtmlString(Model.WithMediaflowMetadata()); }

Felsökning (installation och drift)