core コレクション モデルのファセットの使用

Current version: 10.1

xConnect は、複数の組み込みファセットを定義しています。これらのファセットは Sitecore.XConnect.Collection.Model 名前空間にあります。

core コレクション モデルの参照

次の例は、独自のモデルで Sitecore.XConnect.Collection.Model.CollectionModel.Model を参照する方法を示しています。

RequestResponse
xdbModelBuilder modelBuilder = new XdbModelBuilder("ModelName", new XdbModelVersion(0,1));
modelBuilder.ReferenceModel(Sitecore.XConnect.Collection.Model.CollectionModel.Model);

core コレクション モデルのファセットの使用

core コレクション モデル内のファセットを操作するには、次のようにデフォルトのファセット キーを使用します。

RequestResponse
var avatarFacet = contact.GetFacet<Avatar>(Avatar.DefaultFacetKey);

すべての組み込みファセットには、DefaultFacetKey プロパティで表されるデフォルトのファセット キー (PersonalInformation.DefaultFacetKey など) があります。

コンタクト ファセット

PersonalInformation (PersonalInformation)

PersonalInformation ファセットには、必須のプロパティがありません。

RequestResponse
PersonalInformation personal = new PersonalInformation();

personal.Birthdate = new DateTime(1901, 01, 20).ToUniversalTime();
personal.JobTitle = "xDB Enthusiast";
personal.LastName = "McSitecore";
personal.MiddleName = "";
personal.FirstName = "Myrtle";
personal.Gender = "Female";
personal.PreferredLanguage = "English";
personal.Suffix = "the Magnificent";
personal.Title = "Miss";
personal.Nickname = "Myrtle the Cool";

client.SetFacet<PersonalInformation>(new FacetReference(contact, PersonalInformation.DefaultFacetKey), personal);

クライアントでは .SetPersonal() の拡張機能を使用することもできます。

RequestResponse
client.SetPersonal(contact, personal);

EmailAddressList 

RequestResponse
var preferredEmail = new EmailAddress("sample@sitecore.test", true);
var preferredKey = "Work";

var emailFacet = new EmailAddressList(preferredEmail, preferredKey)
{
    Others = new Dictionary<string, EmailAddress>()
    {
        { "Spam",  new EmailAddress("spam@me.com", false) }
    },
};

client.SetFacet<EmailAddressList>(new FacetReference(contact, EmailAddressList.DefaultFacetKey), emailFacet);
重要

優先するメールは .Others リストに含まれません。

クライアントでは .SetEmails() の拡張機能を使用することもできます。

RequestResponse
client.SetEmails(contact, emailFacet);

AddressList 

RequestResponse
// Preferred address
Address preferredAddress = new Address()
{
    AddressLine1 = "Slartibartfast Mansion",
    AddressLine2 = "42",
    AddressLine3 = "Douglas Road",
    AddressLine4 = "Adams Common",
    City = "Sqornshellous",
    CountryCode = "UK",
    GeoCoordinate = new GeoCoordinate(51.507351f, -0.127758f),
    PostalCode = "AB1 2CD",
    StateOrProvince = "Dragonville"
};

AddressList addressList = new AddressList(preferredAddress, "Home");

Address workAddress = new Address()
{
    AddressLine1 = "44 Work Street",
    City = "Work City",
    CountryCode = "DK"
};

addressList.Others.Add("Work", workAddress);
重要

優先するアドレスは .Others リストに含まれません。

クライアントでは .SetAddresses() の拡張機能を使用することもできます。

RequestResponse
client.SetAddresses(contact, addressList);

PhoneNumberList

RequestResponse
var countryCode = "44";
var number = "(555) 555-5555"

PhoneNumber mainNumber = new PhoneNumber(countryCode, number)
{
    Extension = "5",
    AreaCode = "917"  
};

PhoneNumberList numbers = new PhoneNumberList(mainNumber, "Home");

PhoneNumber mobileNumber = new PhoneNumber()
{
    CountryCode = "44",
    Number = "07912345678"
};

numbers.Others.Add("Mobile", mobileNumber);
重要

優先する電話番号は Others リストに含まれません。

クライアントでは .SetPhoneNumbers() の拡張機能を使用することもできます。

RequestResponse
client.SetPhoneNumbers(contact, numbers);

ConsentInformation

注記

ConsentInformation ファセットは Sitecore 10.0 で変更されました。

次の例は、ConsentInformation ファセット クラスのインスタンスを設定し、ディクショナリに 2 つの同意アイテムを追加する方法を示しています。1 つはデフォルト サイト (website) 用で、1 つはカスタム サイト (subsite) 用です。

RequestResponse
var consentInformation = new ConsentInformation();

consentInformation.Consents.Add("website", new ConsentItem
{
    ConsentDateTime = DateTime.UtcNow,
    ConsentValue = 1 // Consent given
});

consentInformation.Consents.Add("subsite", new ConsentItem
{
    ConsentDateTime = DateTime.UtcNow,
    ConsentValue = 0 // Consent not given
});

consentInformation.Consents["website"].ConsentValue = 0; // Update consent
consentInformation.Consents["website"].ConsentDateTime = DateTime.UtcNow; // Update consent time

EXM は doNotMarket 値と consentRevoked 値を読み取って変更するための拡張メソッドを提供します。

RequestResponse
var doNotMarket = consentInformation.IsDoNotMarket();
var consentRevoked = consentInformation.IsConsentRevoked();

クライアントでは .SetConsentInformation() の拡張機能を使用することもできます。

RequestResponse
client.SetConsentInformation(contact, consent);

ListSubscriptions

RequestResponse
ListSubscriptions subscriptions = new ListSubscriptions();

var listId = Guid.NewGuid(); /* Replace with real list ID */
var isActive = true;
var added = DateTime.UtcNow;

ContactListSubscription subscription = new ContactListSubscription(added, isActive, listId);

subscriptions.Subscriptions.Add(subscription);

このファセットを設定するには、クライアントで .SetListSubscriptions() の拡張機能を使用できます。

RequestResponse
client.SetListSubscriptions(contact, subscriptions);

コンタクトリストの定義の取得

ContactListSubscription にはリスト ID が格納されます。リストの詳細 (リスト名など) にアクセスする場合は、コンタクト リスト定義マネージャー (マーケティング オペレーション API の一部) を使用します。

AutomationPlanEnrollmentCache 

AutomationPlanEnrollmentCache には、コンタクトの現在のオートメーション プランの登録が含まれています。これには、コンタクトが登録されているアクティビティも含まれます。このファセットは、コンタクトが新しいプランやアクティビティに登録されるたびに、Automation Engine によって設定されます。

重要

このファセットを手動で設定しないでください。ファセットは、マーケティング オートメーション オペレーション API によって更新されます。

RequestResponse
AutomationPlanEnrollmentCache enrollmentCache = new AutomationPlanEnrollmentCache();

foreach (var enrollment in enrollmentCache.ActivityEnrollments)
{
    Guid activityID = enrollment.ActivityId;
    Guid planID = enrollment.AutomationPlanDefinitionId;
    DateTime entryDate = enrollment.ActivityEntryDate; // Entry date for activity
    string contextKey = enrollment.ContextKey;
}

このファセットを取得するには、次の手順に従います。

RequestResponse
var facet = contact.GetFacet<AutomationPlanEnrollmentCache>(AutomationPlanEnrollmentCache.DefaultFacetKey);

プランおよびアクティビティの定義の取得

AutomationPlanEnrollment にはアクティビティ ID とプラン ID が格納されます。プランやアクティビティに関する詳細 (名前など) にアクセスする場合は、オートメーション プラン定義マネージャー (マーケティング オペレーション APIの一部) を使用します。

アバター

RequestResponse
var pictureByteArray = new byte[] { 0x20, 0x20, 0x20, 0x20, 0x20, 0x20, 0x20 };
var mimeType = "image/jpeg";

Avatar avatar = new Avatar(pictureByteArray, mimeType);

このファセットを取得するには、次の手順に従います。

RequestResponse
var facet = contact.GetFacet<Avatar>(Avatar.DefaultFacetKey);

クライアントでは .SetAvatar() の拡張機能を使用することもできます。

RequestResponse
client.SetAvatar(contact, avatar);

計算されたコンタクト ファセット

次の計算されたコンタクト ファセットはデフォルトで使用できます。

重要

計算されたファセットのバリューは絶対に設定しないでください。これらは、インタラクションが xConnect に送信されるたびにサービス プラグインによって設定されます。

インタラクション ファセット

UserAgentInfo 

RequestResponse
UserAGentInfo userAgentInfo = new UserAgentInfo();

userAgentInfo.CanSupportTouchScreen = true;
userAgentInfo.DeviceType = "Mobile";
userAgentInfo.DeviceVendor = "HTC"
userAgentInfo.DeviceVendorHardwareModel = "HTC Desire"

IpInfo

RequestResponse
var ipAddress = "8, 8, 8, 8";

IpInfo ipInfo = new IpInfo(ipAddress);

ipInfo.Isp = "Super Duper Internet";
ipInfo.Latitude = 55.673977;
ipInfo.Longitude = 12.568730;
ipInfo.MetroCode = "408";
ipInfo.AreaCode = "205";
ipInfo.BusinessName = "Bizniz";
ipInfo.City = "Super City";
ipInfo.Country = "Narnia";
ipInfo.PostalCode = "12A 24B";
ipInfo.Region = "Icy Plains";
ipInfo.Url = "host.local";
ipInfo.Dns = "dnsvalue";

このファセットを取得するには、次の手順に従います。

RequestResponse
var facet = interaction.GetFacet<IpInfo>IpInfo.DefaultFacetKey);

クライアントでは .SetIpInfo() の拡張機能を使用することもできます。

RequestResponse
client.SetIpInfo(interaction, ipInfo);

ProfileScores

RequestResponse
ProfileScore profileScore = new ProfileScore()
{
    MatchedPatternId = Guid.NewGuid(), // Guid of matched profile
    ProfileDefinitionId = Guid.NewGuid(), // Guid of profile
    Score = 1.9f,
    ScoreCount = 3,
    Values = new Dictionary<Guid, float>() { { Guid.NewGuid(), 1.2f }, { Guid.NewGuid(), 1.2f } }
};

ProfileScores profiles = new ProfileScores();

profiles.Scores.Add(Guid.NewGuid(), profileScore);

// NOTE: The Scores dictionary key should be the profile definition ID as a Guid

WebVisit

WebVisit ファセットには、Web サイトで発生したインタラクションに関する情報が格納されます。Sitecore コンテキストでは、このファセットはセッション終了時にトラッカーによって設定されます。次の例は、WebVisit ファセットを設定し、複数の PageViewEvent イベントをインタラクションに追加して、Web 訪問のイミテーションを行う方法を示しています。

RequestResponse
using Sitecore.XConnect;
using Sitecore.XConnect.Collection.Model;
using System;

namespace Documentation
{
    public class SampleWebVisit
    {
        public async void Example()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                // Create a new contact and set some facets
                var contact = new Contact();

                var personalInfoFacet = new PersonalInformation()
                {
                    FirstName = "Myrtle",
                    LastName = "McSitecore"
                };

                client.SetPersonal(contact, personalInfoFacet);

                client.AddContact(contact);

                // Create a new interaction for the contact
                Guid channelId = Guid.NewGuid();
                string userAgent = "Sample User Agent";
                Interaction webInteraction = new Interaction(contact, InteractionInitiator.Brand, channelId, userAgent);

                // Create a new web visit facet model
                var webVisitFacet = new WebVisit();

                // Populate data about the web visit
                webVisitFacet.Browser = new BrowserData() { BrowserMajorName = "Chrome", BrowserMinorName = "Desktop", BrowserVersion = "22.0" };
                webVisitFacet.Language = "en";
                webVisitFacet.OperatingSystem = new OperatingSystemData() { Name = "Windows", MajorVersion = "10", MinorVersion = "4" };
                webVisitFacet.Referrer = "www.google.com";
                webVisitFacet.Screen = new ScreenData() { ScreenHeight = 1080, ScreenWidth = 685 };
                webVisitFacet.SearchKeywords = "sitecore";
                webVisitFacet.SiteName = "website";

                var itemId = Guid.NewGuid();
                var itemVersion = 5;

                // First page view
                 pageView = new PageViewEvent(new DateTime(2016, 10, 10, 13, 20, 22).ToUniversalTime(), itemId, itemVersion, "en");

                pageView.ItemLanguage = "en";
                pageView.Duration = new TimeSpan(3000);

                webInteraction.Events.Add(pageView);

                var secondItemId = Guid.NewGuid();
                var secondItemVersion = 2;

                // Second page view
                PageViewEvent pageView2 = new PageViewEvent(new DateTime(2016, 10, 10, 13, 21, 22).ToUniversalTime(), secondItemId, secondItemVersion, "en");

                pageView.ItemLanguage = "en";
                pageView.Duration = new TimeSpan(3200);

                webInteraction.Events.Add(pageView2);

                // First goal, associated with second page view
                Goal goal1 = new Goal(Guid.NewGuid(), new DateTime(2016, 10, 10, 13, 22, 22).ToUniversalTime());

                goal1.ParentEventId = pageView2.Id;

                webInteraction.Events.Add(goal1);

                var thirdItemId = Guid.NewGuid();
                var thirdItemVersion = 2;

                // Third page view
                PageViewEvent pageView3 = new PageViewEvent(new DateTime(2016, 10, 10, 13, 22, 22).ToUniversalTime(), thirdItemId, thirdItemVersion, "en");

                pageView.ItemLanguage = "en";
                pageView.Duration = new TimeSpan(1200);

                webInteraction.Events.Add(pageView3);

                // Set web visit facet on interaction
                client.SetWebVisit(webInteraction, webVisitFacet);

                // Add interaction
                client.AddInteraction(webInteraction);

                // Submit contact and interaction
                await client.SubmitAsync(); // Synchronous version - client.SubmitAsync().GetAwaiter().GetResult();
            }
        }
    }
}

LocaleInfo 

RequestResponse
LocaleInfo localeInfo = new LocaleInfo();

localeInfo.TimeZoneOffset = new TimeSpan(200);
localeInfo.GeoCoordinate = new GeoCoordinate(1.11111f, 2.22222f);

クライアントでは .SetLocaleInfo() の拡張機能を使用することもできます。

RequestResponse
client.SetLocaleInfo(interaction, localeInfo);

ファセットの get/set 拡張メソッド

usingSitecore.XConnect.Collection.Model をクラスに追加して、コンタクト、インタラクション、xConnect クライアントの複数の拡張メソッドにアクセスし、組み込みファセットの取得と設定を容易にします。たとえば、myContact.Personal() は次のメソッドを呼び出します。

RequestResponse
public static PersonalInformation Personal(this Contact c)
{
    return c.GetFacet<PersonalInformation>(PersonalInformation.DefaultFacetKey);
}

同様に、client.SetAddresses(myContactObject,myFacetObject) は次のメソッドを呼び出します。

RequestResponse
public static SetFacetOperation<AddressList> SetAddresses(this XdbContext context, IEntityReference<Contact> contact, AddressList facet)
{
    return context.SetFacet(new FacetReference(contact, PersonalInformation.DefaultFacetKey), facet);
}

Do you have some feedback for us?

If you have suggestions for improving this article,