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. Version 1.2.2 lägger till stöd för SVG samt dedikerade property-typer för bild, video och SVG.

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. 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 version 1.2.2 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/package/?id=Mediaflow.Optimizely

Steg 2 – Installera NuGet-paketet

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

dotnet add package Mediaflow.Optimizely --version 1.2.2

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.

Valfritt: Protected module i appsettings.json

Från version 1.2.x registreras den skyddade modulen automatiskt när AddMediaflow() anropas i Startup.cs. Du behöver alltså inte längre en separat EPiServer:CmsUI:ProtectedModule-post – men du kan ange den explicit som reserv om du föredrar det:

"EPiServer": {
  "CmsUI": {
    "ProtectedModule": {
      "Items": [
        { "Name": "Mediaflow.Optimizely" }
      ]
    }
  }
}

Steg 4 – Registrera integrationen i Startup.cs

Tre registreringsanrop är obligatoriska för att integrationen ska fungera. Lägg till dem i Startup.cs eller motsvarande i din Program.cs.

ConfigureServices

Välj alternativet som passar din webbplats.

Alternativ A – webbplatsen aktiverar inte redan Razor runtime compilation

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

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddCms()
        // ... övriga Optimizely-tjänster ...
        .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:

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 inbäddade views – 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 CmsAdmins, 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 och ingen servernyckel är satt kan endast användare i rollerna Mediaflow, Administrators, WebAdmins eller CmsAdmins autentisera mot Mediaflow.

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 "*".

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

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.

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 CmsAdmins-användare, ö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.

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.

Felsökning (installation och drift)